@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:

1. Abre o Chrome (Playwright), acessa a página de login e aguarda o usuário fazer login (o email é preenchido automaticamente se informado).
2. Obtém o cookie tarefy (token da API HTTP do Tarefy).
3. Salva o token em ~/.tarefy-mcp/token.txt para 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:

1. Lê o token salvo por login (se não houver, retorna erro orientando a usar login primeiro).
2. Obtém os dados gerais da task, as conversas internas e as conversas públicas pela API do Tarefy.
3. Sem prompt: devolve um JSON no formato { task, comments, publicComments }. Com prompt: 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 <token>

O <token> é 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