Task CLI + MCP

Aplicação de linha de comando para gerenciamento de tarefas, estendida com um servidor MCP (Model Context Protocol) que expõe operações da aplicação para clientes de IA através de tools estruturadas, evitando chamadas de shell e parsing manual de saída.

Este projeto foi desenvolvido como um exercício de arquitetura, integração com IA e desenvolvimento orientado por especificação. O foco de engenharia está na separação entre domínio e interfaces: a lógica de negócio existe uma única vez e é consumida tanto pela CLI quanto pela camada MCP.

• Especificação do produto (fonte de verdade): docs/spec.md

• Documento de arquitetura: docs/architecture.md

• Servidor MCP (instalação, registro, tools): mcp/README.md

Overview

O projeto começou como uma CLI de um comando, com três operações e persistência em arquivo:

• adicionar tarefas — cria uma tarefa pendente, atribui um id inteiro incremental (nunca reutilizado) e confirma o id;

• listar tarefas — mostra id, status (pendente/concluída) e descrição; informa explicitamente quando não há tarefas;

• concluir tarefas — marca uma tarefa pendente como concluída; se já estiver concluída, apenas informa e encerra normalmente.

A persistência é local, em um tasks.json na raiz do projeto, resolvido relativamente à raiz do repositório (independe do diretório de trabalho). A ausência do arquivo equivale a uma lista vazia; a primeira gravação o cria. Um tasks.json com JSON inválido faz qualquer comando falhar com mensagem clara e sem sobrescrever o arquivo.

Numa segunda fase o repositório ganhou uma camada MCP. Ela não é um produto novo: reusa a mesma camada de domínio e o mesmo armazenamento, sem duplicar regras. O núcleo (src/) não mudou para a extensão existir e continua sem dependências externas.

Related MCP server: questlog-mcp

Architecture

src/ — núcleo, sem dependências externas

mcp/ — camada adaptadora

O MCP funciona como camada adaptadora sobre o domínio. A lógica de negócio permanece independente da interface: as tools consomem src/, e src/ não conhece mcp/. As dependências do SDK de MCP ficam confinadas a mcp/ e ao package.json da raiz.

Detalhes, diagramas e trade-offs: docs/architecture.md.

MCP Integration

• Servidor: mcp/server.js (inicie com npm run mcp ou node mcp/server.js)

• Transporte: JSON-RPC 2.0 sobre stdio. stdout é reservado ao protocolo; o diagnóstico de conexão (task-cli MCP server conectado (stdio)) vai para stderr.

Tools disponíveis

project_status não altera estado e não modifica tasks.json: nunca chama a persistência, reutiliza a camada de domínio apenas para ler as tarefas, e consulta Git/package.json só para leitura. Falha ao consultar o Git (fora de um repositório, git ausente no PATH) resulta em null no campo correspondente, sem derrubar o servidor.

Formato do retorno de project_status:

{
  "projectName": "claude-lab",
  "git": { "branch": "main", "lastCommit": "<hash> <assunto>" },
  "tasks": { "total": 3, "done": 1, "pending": 2 }
}

Example Usage

CLI

$ node src/index.js add "Estudar MCP"
Tarefa 1 adicionada

$ node src/index.js list
[ ] 1  Estudar MCP

$ node src/index.js done 1
Tarefa 1 concluída

MCP / Claude Code

O cliente de IA faz a negociação MCP e então chama as tools. Um diálogo típico:

Usuário: "Crie uma tarefa chamada estudar MCP" Claude: chama add_task com { "description": "estudar MCP" } Resultado: Tarefa 1 adicionada (structuredContent: { id: 1, description: "estudar MCP", done: false })

Usuário: "Liste minhas tarefas" Claude: chama list_tasks com {} Resultado: [ ] 1 estudar MCP

Usuário: "Qual o status do projeto?" Claude: chama project_status com {} Resultado: nome, branch, último commit e contagem de tarefas — sem tocar em tasks.json

Como CLI e MCP usam o mesmo tasks.json, uma tarefa criada por add_task aparece em node src/index.js list, e vice-versa.

Technical Highlights

• Separação entre domínio e interfaces. As regras vivem só em src/task-service.js; CLI e MCP são bordas finas por cima.

• MCP como adaptador, não produto novo. Nenhuma regra reimplementada em mcp/; o núcleo permanece sem dependências externas.

• JSON-RPC 2.0 sobre stdio. stdout exclusivo do protocolo; logs em stderr — condição para o cliente MCP não quebrar o parsing.

• Integração com Claude Code. As quatro tools são chamáveis diretamente por um cliente de IA, incluindo project_status para contexto de repositório.

• Testes unitários para o domínio, a CLI e as tools MCP.

• Teste de integração que sobe o servidor MCP real como subprocesso e exercita o handshake initialize → tools/list → tools/call por JSON-RPC.

• Isolamento de armazenamento nos testes. O caminho do tasks.json é injetável; as suítes usam armazenamento temporário e nenhum teste escreve no tasks.json real.

• Sem duplicação de regra de negócio. Um único ponto de verdade para validação, contagem e semântica de persistência.

Testing

node --test

Test runner nativo do Node.js (node:test), sem framework. Atualmente 9 suítes em test/, 84 testes, todos passando:

• Domínio — test/task-service.test.js (regras puras, imutabilidade, nextId).

• CLI — test/add.test.js, test/list.test.js, test/done.test.js, test/cli.test.js (comportamento ponta a ponta, ajuda de uso, exit codes).

• Tools MCP — test/mcp-tools.test.js (as três tools de tarefa), test/project-status.test.js (formato do contrato, estado vazio, contagem, arquivo corrompido, somente leitura).

• Integração MCP — test/mcp-server-integration.test.js (servidor real sobre stdio; valida que stdout só carrega JSON-RPC e que o tasks.json real não muda).

• Hook do laboratório — test/block-agent-commit.test.js.

Algumas suítes sobem subprocessos (CLI, hook, servidor MCP) para validar comportamento de entrada real; as demais chamam as funções diretamente.

Design Decisions

• Por que o MCP não fica dentro de src/. O núcleo é stdlib-only por contrato — testável, sem árvore de dependências, fácil de auditar. O SDK de MCP (@modelcontextprotocol/sdk) é uma dependência real e fica isolada em mcp/. As tools consomem src/; a dependência nunca vaza para o domínio.

• Por que project_status é somente leitura. Não existe operação de escrita de "status" no produto. Torná-la só-leitura evita expandir o escopo, mantém a tool segura de chamar a qualquer momento e permite degradação graciosa quando o Git não está disponível (campos null em vez de erro).

• Por que manter tasks.json nesta versão. O apetite do projeto é pequeno: um arquivo JSON local resolve a persistência sem servidor, sem schema, sem migração. Trocar por um banco só se justifica se o escopo crescer.

• Trade-offs aceitos. Sem controle de concorrência — CLI e servidor MCP gravando ao mesmo tempo podem se sobrescrever (documentado como No-go). project_status invoca git de forma síncrona (execFileSync, sem shell, com timeout), o que bloqueia o event loop do servidor por alguns segundos no pior caso e não tem cache.

Future Improvements

Fora do escopo atual, mas compatíveis com a arquitetura:

• Persistência em banco (SQLite/Postgres) atrás da mesma interface de store.js, sem tocar no domínio.

• Controle de concorrência — lock cooperativo de arquivo entre CLI e servidor MCP.

• Autenticação para MCP remoto, caso o transporte deixe de ser stdio local.

• Cache de informações Git em project_status (TTL curto) para eliminar o custo de subprocesso por chamada; alternativamente, git assíncrono.

• Observabilidade — logs estruturados em stderr e métricas básicas de uso das tools.