Primeiro projeto com ClickUpfy e MCP, passo a passo

Classificação

O que você vai preparar

Neste percurso, um repositório será ligado a uma List do ClickUp. O resultado é um .mcp.json que inicia o ClickUpfy com um account e IDs fixos, além das quatro skills instaladas no projeto.

Antes de escrever qualquer tarefa, você vai:

1. validar o perfil
2. descobrir Space, Folder e List
3. instalar o MCP em read-only para conferir o destino
4. liberar escrita somente depois da revisão.

Valide o perfil

1
clickupfy status
2
clickupfy whoami

Confirme o nome do account, o usuário e o workspace. Se qualquer dado estiver errado, volte à configuração.

Descubra a hierarquia

1
clickupfy workspace list
2
clickupfy space list
3
clickupfy folder list --space <space-id>
4
clickupfy list list --folder <folder-id>

Uma List pode pertencer diretamente ao Space. Nesse caso:

1
clickupfy list list --space <space-id>

Guarde os IDs confirmados. Se o projeto usa Sprints, localize também o Sprint Folder que contém as Lists temporais.

Inicialize o agente

Na raiz do repositório:

1
clickupfy --account promovaweb agent init \
2
  --workspace 123 \
3
  --space 10 \
4
  --folder 20 \
5
  --list 30

space e list são obrigatórios. Workspace e Folder podem ser omitidos quando não forem necessários ao escopo. Acrescente --sprint-folder <id> se o projeto usa Sprints.

O comando instala as skills e mescla o servidor no .mcp.json existente sem remover outros servidores:

1
{
2
  "mcpServers": {
3
    "promovaweb-clickupfy": {
4
      "command": "clickupfy",
5
      "args": [
6
        "mcp",
7
        "serve",
8
        "--account",
9
        "promovaweb",
10
        "--workspace",
11
        "123",
12
        "--space",
13
        "10",
14
        "--folder",
15
        "20",
16
        "--list",
17
        "30"
18
      ]
19
    }
20
  }
21
}

Antes de abrir o cliente MCP pela primeira vez, acrescente --read-only ao fim de args. O agent init prepara o servidor completo. Essa edição consciente reduz a superfície durante a conferência inicial.

Confira no agente

Reinicie ou recarregue o cliente MCP para que ele leia a nova configuração. Peça uma consulta ao contexto:

1
Use clickupfy_mcp_context e mostre o perfil, o workspace e a hierarquia deste
2
projeto.

Compare o resultado com os IDs anotados. Depois liste as tarefas:

1
Use clickupfy_tasks_list sem informar listId.

O servidor deve aplicar a List configurada. Uma tentativa de consultar outra List deve ser recusada.

Libere escrita

Quando o destino estiver correto, remova apenas --read-only da entrada gerenciada. Reabra o cliente MCP e confirme que as ferramentas de escrita aparecem em tools/list.

Crie uma tarefa de teste somente se o projeto e a equipe autorizarem a mutação. Caso contrário, use uma tarefa real já existente para validar leitura, comentários e checklists.

Primeira leitura de uma tarefa

No terminal:

1
clickupfy task get <task-id> --markdown

No agente:

1
Leia <task-id> com clickupfy_task_get usando markdown: true. Não altere a
2
tarefa.

Confira descrição, subtarefas, checklists e fila executável. Agora você já pode aprofundar a hierarquia ou começar a trabalhar com tarefas.