noclaf-mcp

MCP server + CLI pra controlar o NOS (Noclaf Operation System) a partir do Claude Code, Codex CLI e GitHub Copilot.

O que faz

Permite ao assistente de IA:

• Ler contexto do projeto (membros, sprint ativa, repositórios vinculados)
• Listar, criar, atualizar, mover entre colunas e comentar tarefas
• Bater ponto e cronometrar tempo em tarefas específicas

Instalação (mac / linux / windows)

Precisa apenas de Node.js 20+. Instala como pacote global:

npm i -g @noclaf/mcp

Pronto. Os comandos noclaf (CLI) e noclaf-mcp (servidor MCP) ficam disponíveis no PATH em qualquer SO.

Configurar em qualquer repo

Na raiz do repositório:

noclaf init

Esse único comando faz tudo:

1. Pede o seu PAT se você ainda não está autenticado (gera em https://nos.noclaf.com.br/profile#mcp).
2. Lista os projetos do NOS e você escolhe um (ou cola o UUID).
3. (Opcional) Escolhe o repositório vinculado.
4. Escreve noclaf.json na raiz.
5. Mostra o contexto carregado pra você validar.
6. Pergunta quais clientes MCP configurar — global ou por-repo.

Reinicie o cliente de IA depois pra carregar as tools.

Comandos do CLI

| Comando | Descrição | | ---------------------------------------------------- | -------------------------------------------------------- | | noclaf init | Faz tudo: autentica, vincula projeto, configura clientes | | noclaf login [pat] | Salva o PAT (interativo se omitido) | | noclaf logout | Apaga as credenciais | | noclaf whoami | Mostra o usuário autenticado | | noclaf install-client <claude-code\|codex\|vscode> | Registra o MCP num cliente globalmente (avulso) | | noclaf install-client cowork | Gera o .mcpb (Desktop Extension) em ~/Downloads | | noclaf --version | Imprime a versão |

Tools disponíveis

15 tools no MCP, divididas em quatro grupos.

Projeto

| Tool | O que faz | | ------------------- | ------------------------------------------------------------------------ | | nos_get_context | Snapshot do projeto ativo: nome, repos, sprint ativa, membros, você | | nos_list_projects | Lista os projetos que você acessa (marca o ativo) | | nos_set_project | Define o projeto ativo da sessão (só em memória, dura enquanto o servidor roda) |

Escopo do projeto. As tools de tarefa/alocação resolvem o projeto nesta ordem: argumento project_id da chamada → projeto ativo da sessão (nos_set_project) → default opcional de CLI de código (noclaf.json/NOCLAF_PROJECT_ID).

O projeto ativo é por sessão: vive só em memória, no processo do servidor MCP, e não é gravado em disco — ao reiniciar volta ao default. No Cowork, onde não há noclaf.json, é sempre assim que se escolhe o projeto: nos_list_projects → nos_set_project. (Como um processo do Claude Desktop pode ser compartilhado entre conversas, passe project_id direto na chamada quando quiser garantir o escopo de uma conversa específica.)

Tarefas

| Tool | O que faz | | ------------------ | ----------------------------------------------------------------------------- | | nos_list_tasks | Lista tarefas filtradas por status, assignee, sprint, prioridade, tipo, busca | | nos_get_task | Detalhes completos de uma tarefa | | nos_create_task | Cria nova tarefa (default: status=todo, sprint=active, assignee=você) | | nos_update_task | Atualiza campos de uma tarefa | | nos_move_task | Atalho pra mudar o status | | nos_comment_task | Adiciona comentário em uma tarefa |

Alocações (ponto + cronometragem)

| Tool | O que faz | | --------------------------- | ------------------------------------------------- | | nos_start_allocation | Bate o ponto | | nos_end_allocation | Encerra o ponto do dia | | nos_start_task_allocation | Começa a cronometrar uma task | | nos_end_task_allocation | Para de cronometrar a task atual | | nos_get_active_allocation | Estado atual: ponto, task ativa, segmentos do dia | | nos_list_my_allocations | Histórico de pontos |

Claude Desktop / Cowork (Desktop Extension .mcpb)

Pra usar no app de desktop do Claude ou no Cowork, gere uma extensão .mcpb:

noclaf install-client cowork

Isso empacota o servidor (dist + dependências + manifest.json) num arquivo ~/Downloads/noclaf-mcp-<versão>.mcpb. Pra instalar:

Configurações → Extensões → Configurações avançadas → seção "Extension Developer" → "Install Extension…" → selecione o .mcpb → preencha só o PAT.

Não há projeto pra configurar na instalação: o Cowork não tem noclaf.json (não tem working dir/repo), então o projeto é escolhido por sessão — peça pro assistente rodar nos_list_projects e depois nos_set_project com o id desejado.

Diferente da CLI, a extensão não usa noclaf login/noclaf.json: a única config vem do user_config da extensão, injetada como variável de ambiente:

| Variável | Origem (user_config) | Sensível | | ------------ | ---------------------- | -------- | | NOCLAF_PAT | PAT (noc_…) | ✅ sim |

Override de default (avançado, opcional). Fora do Cowork, em CLIs de código, você ainda pode definir NOCLAF_PROJECT_ID/NOCLAF_REPOSITORY_ID no env do cliente MCP pra fixar um projeto default — equivalente ao noclaf.json. O projeto da sessão (nos_set_project) e o project_id por chamada sempre têm precedência sobre esse default.

Atualizando

npm i -g @noclaf/mcp@latest

A CLI também avisa em background quando uma nova versão sai (via update-notifier).

Troubleshooting

• noclaf-mcp: command not found — confirme o install global com npm i -g @noclaf/mcp e que npm bin -g está no PATH.
• Tools não aparecem no Claude Code — reinicie o Claude Code depois do noclaf init. Confira com /mcp dentro dele.
• Não autenticado — rode noclaf init (que já faz login inline) ou noclaf login. No Cowork, confira se o PAT foi preenchido na extensão.
• Nenhum projeto selecionado — escolha o projeto da sessão: nos_list_projects → nos_set_project. (Em CLI de código você também pode rodar noclaf init pra criar um noclaf.json default no repo.)

Convenções

• Idioma: UI/CLI em pt-BR. Código (variáveis, funções, tipos) em inglês.
• Backups: qualquer escrita em arquivo de config existente gera .bak.<timestamp> ao lado.
• stdout reservado pro JSON-RPC no MCP server — logs vão pra stderr.

Versão

v0.1.x — feature complete pra v1. Próximos passos: testes automatizados, suporte a múltiplos perfis de usuário.