@alanvncs/tarefy-mcp
Servidor MCP para o Tarefy. Expõe tarefas, conversas internas e conversas públicas para uso por agentes de IA (por exemplo no Cursor).
O que é o Tarefy
Tarefy é uma plataforma de gestão de tarefas e produtividade para equipes, empresas e freelancers: criar tarefas, atribuir responsáveis, definir prazos, acompanhar progresso e centralizar a comunicação. Este servidor MCP expõe as informações completas das tasks (dados gerais + conversas) para agentes de IA.
Instalação do MCP
No Cursor, edite ~/.cursor/mcp.json (ou o equivalente no seu sistema) e adicione:
{
"mcpServers": {
"tarefy": {
"command": "npx",
"args": ["@alanvncs/tarefy-mcp@latest"]
}
}
}Reinicie o Cursor para carregar o servidor.
Ferramentas
login
Autentica no Tarefy para que as demais ferramentas possam usar a API.
| Parâmetro | Tipo | Descrição |
|---|---|---|
email | opcional | Email do usuário; se informado, o campo de email é preenchido no navegador. |
Comportamento:
- Abre o Chrome (Playwright), acessa a página de login e aguarda o usuário fazer login (o email é preenchido automaticamente se informado).
- Obtém o cookie
tarefy(token da API HTTP do Tarefy). - Salva o token em
~/.tarefy-mcp/token.txtpara uso pelas outras ferramentas.
Requisito: Chrome instalado (o Playwright usa o canal chrome).
get-task
Obtém os dados completos de uma task: dados gerais, conversas internas (equipe) e conversas públicas (cliente).
| Parâmetro | Tipo | Descrição |
|---|---|---|
taskId | obrigatório | ID da task, o mesmo da URL: https://app.tarefy.com/task/{{taskId}}. |
prompt | opcional | Instruções sobre formato/conteúdo da resposta. Se omitido, retorna todos os dados em JSON. |
Comportamento:
- Lê o token salvo por
login(se não houver, retorna erro orientando a usarloginprimeiro). - Obtém os dados gerais da task, as conversas internas e as conversas públicas pela API do Tarefy.
- Sem
prompt: devolve um JSON no formato{ task, comments, publicComments }. Comprompt: devolve o mesmo JSON precedido das instruções informadas (para o cliente/agente interpretar ou reformatar).
API do Tarefy (usada pelo servidor)
O servidor chama a API HTTP do Tarefy com os seguintes detalhes.
Headers em todas as requisições:
Content-Type: application/json
Authorization: Bearer O ` é o valor do cookie tarefy obtido após o login (salvo em ~/.tarefy-mcp/token.txt`).
Endpoints:
| Recurso | Método | URL | Observação |
|---|---|---|---|
| Dados da task | GET | https://app.tarefy.com/nodeapi/v2/tasks/{{taskId}} | taskId = ID da URL da task (ex.: /task/12345 → 12345). |
| Conversas internas | GET | https://app.tarefy.com/nodeapi/task/comments?id={{ticketId}} | ticketId = campo id retornado nos dados gerais da task. |
| Conversas públicas | GET | https://app.tarefy.com/nodeapi/task/comments/client?id={{ticketId}} | Idem: ticketId = id dos dados gerais. |
- Conversas internas: alinhamentos da equipe, eventos sistêmicos (ex.: mudança de área); não visíveis para o cliente.
- Conversas públicas: aprovações, prazos, pedidos de dados, dúvidas; visíveis para o cliente.
Desenvolvimento
Requisitos: Node ≥ 18, Bun (gerenciador de pacotes).
| Comando | Descrição |
|---|---|
bun install | Instalar dependências |
bun run build | Compilar TypeScript → build/ |
bun run start | Rodar o servidor (node build/index.js) |
bun run dev | Rodar sem build (bun run src/index.ts) |
bun run inspector | Testar o servidor com MCP Inspector (build + UI em http://localhost:6274) |
bun test | Testes unitários |
bun run lint | ESLint |
bun run format | Prettier (formatação) |
O binário publicado no npm é build/index.js (uso com npx ou como tarefy-mcp após instalação global).
Publicação no npm: o workflow do GitHub usa Trusted Publishing (OIDC); não é necessário configurar NPM_TOKEN. É preciso registrar o Trusted Publisher uma vez em npmjs.com → Package → Settings → Trusted publishing (repositório e nome do workflow: publish-npm.yml). O workflow dispara em push de tags v* (ex.: v0.1.2) ou manualmente. Para criar uma nova versão e publicar: bun run release (bump patch), ou bun run release -- minor / bun run release -- major. O script (TypeScript, rodado com Bun) faz o bump em package.json, commit com mensagem vX.Y.Z, tag e push; não precisa do GitHub CLI.
Licença
MIT