Worklog MCP

Servidor MCP que conecta o Worklog App ao seu Claude. Registre horas e conhecimento, e consulte clientes/entradas/faturas e o resumo financeiro — tudo por chat, autenticado com uma API key por-tenant gerada no app.

1. Gere sua API key

No Worklog App: Perfil → API keys → Gerar. Copie a chave (wl_…) — ela só é exibida uma vez.

2. Configure no seu cliente

Claude Code (CLI)

claude mcp add worklog -e WORKLOG_API_KEY=wl_suachave -- npx -y @schner/worklog-mcp

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "worklog": {
      "command": "npx",
      "args": ["-y", "@schner/worklog-mcp"],
      "env": {
        "WORKLOG_API_KEY": "wl_suachave",
        "WORKLOG_URL": "https://worklog.schner.dev"
      }
    }
  }
}

WORKLOG_URL é opcional (default https://worklog.schner.dev). Use http://localhost:5179 para apontar pra uma instância local.

Tools

| Tool | O que faz | |---|---| | registrar_entrada | Registra horas por nomes (cria cliente/projeto sob demanda; deduplica) | | listar_entradas | Lista/filtra entradas (cliente, projeto, datas, status) | | listar_clientes | Lista clientes (resolve clienteId) | | listar_projetos | Lista projetos (opcionalmente de um cliente) | | buscar_conhecimento | Busca na base de conhecimento (título/conteúdo/tags) | | ler_conhecimento | Lê o conteúdo completo de um documento | | gravar_conhecimento | Grava um documento técnico (markdown) na KB do cliente | | resumo_financeiro | Dashboard financeiro (pendente, a receber, recebido, por cliente, metas) | | listar_faturas | Lista as faturas |

A key herda o escopo do tenant que a gerou — você só enxerga/edita os dados do seu tenant. Revogue uma key a qualquer momento em Perfil → API keys.

Desenvolvimento

npm install
npm run build          # gera dist/
WORKLOG_API_KEY=wl_... node dist/index.js   # roda o server (stdio)

Distribuição — duas opções:

A) Manual (npm exige 2FA):

npm login
npm publish --otp=123456    # código atual do seu app autenticador

B) CI (sem OTP): crie um token de automação no npm (Access Tokens → Granular, publish + "bypass 2FA"), salve como secret NPM_TOKEN no repo GitHub, e empurre uma tag:

git tag mcp-v0.1.0 && git push origin mcp-v0.1.0

O workflow .github/workflows/publish-mcp.yml builda e publica.

prepublishOnly builda antes; files envia só dist + README + LICENSE. Depois de publicado, npx -y @schner/worklog-mcp resolve do registry.

Convenção MCP/stdio: o stdout é exclusivo do protocolo JSON-RPC. Todo log vai pro stderr.