Lifecycle MCP Server

Um servidor MCP para gerenciar o ciclo de vida do desenvolvimento de software, com suporte para um banco de dados SQLite externo opcional.

GitHub
39

Documentação

Lifecycle MCP Server

Um servidor Model Context Protocol (MCP) para gerenciamento abrangente do ciclo de vida de software. Este servidor fornece rastreamento estruturado de requisitos, tarefas e decisões de arquitetura através de um banco de dados SQLite com rastreabilidade completa e gerenciamento automatizado de estado.

Recursos

  • Gerenciamento de Requisitos: Crie e gerencie requisitos de software com validação e rastreamento de ciclo de vida
  • Gerenciamento de Tarefas: Acompanhe tarefas de implementação com estrutura hierárquica e estimativa de esforço
  • Decisões de Arquitetura: Registre ADRs (Registros de Decisão de Arquitetura) com contexto completo
  • Painéis do Projeto: Métricas de saúde do projeto em tempo real e relatórios de status
  • Rastreamento de Requisitos: Rastreabilidade completa desde os requisitos até a implementação
  • Validação de Estado: Validação automática de transições de estado do ciclo de vida
  • Edição Segura e Histórico: Edite registros no local com histórico por campo, motivos para requisitos aprovados e verificações de revisão; exclua registros criados por engano
  • Rastreamento de Relacionamentos: Relacionamentos muitos-para-muitos entre requisitos, tarefas e arquitetura

Início Rápido

# 1. Clone the repository
git clone https://github.com/heffrey78/lifecycle-mcp.git
cd lifecycle-mcp

# 2. Install globally (easiest for using across projects)
uv tool install .        # or: pip install -e .

# 3. Go to any project where you want to use lifecycle management
cd /path/to/your/project

# 4. Add the MCP server to Claude
claude mcp add lifecycle lifecycle-mcp -e LIFECYCLE_DB=/path/to/your/project/lifecycle.db

# 5. Start using lifecycle tools in Claude!

Opções de Instalação

Pré-requisitos (Opcional)

Se você quiser usar uv (gerenciador de pacotes Python mais rápido):

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or with homebrew
brew install uv

Clonar o Repositório

git clone https://github.com/heffrey78/lifecycle-mcp.git
cd lifecycle-mcp

Uso com Claude Code

Para exemplos detalhados e cenários, consulte USAGE_EXAMPLES.md.

Opção 1: Instalação Global (Recomendado para Múltiplos Projetos)

Instale o servidor globalmente para que possa ser usado a partir de qualquer projeto:

# From the lifecycle-mcp directory (add --editable to pick up source changes)
uv tool install .        # or: pip install -e .

# Now from ANY project directory, add the server:
claude mcp add lifecycle lifecycle-mcp -e LIFECYCLE_DB=./lifecycle.db

Nota: Cada projeto recebe seu próprio arquivo de banco de dados em seu diretório.

Opção 2: Executar a partir do Código Fonte com uv

Se você preferir não instalar globalmente:

# Get the full path to the lifecycle-mcp directory
LIFECYCLE_PATH="/path/to/lifecycle-mcp"  # Replace with your actual path

# From any project directory:
claude mcp add lifecycle $(which uv) -- --directory $LIFECYCLE_PATH run server.py -e LIFECYCLE_DB=./lifecycle.db

Opção 3: Execução Direta em Python

Para máxima compatibilidade:

# Get the full path to the server
LIFECYCLE_PATH="/path/to/lifecycle-mcp"  # Replace with your actual path

# From any project directory:
claude mcp add lifecycle $(which python) $LIFECYCLE_PATH/server.py -e LIFECYCLE_DB=./lifecycle.db

Configuração Manual

Você também pode editar manualmente o arquivo de configuração do Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "lifecycle": {
      "command": "lifecycle-mcp",
      "env": {
        "LIFECYCLE_DB": "./lifecycle.db"
      }
    }
  }
}

Melhores Práticas

Localização do Banco de Dados

  • Cada projeto deve ter seu próprio arquivo lifecycle.db
  • Use LIFECYCLE_DB=./lifecycle.db para criar o banco de dados no projeto atual
  • Ou use um caminho absoluto para um banco de dados compartilhado: LIFECYCLE_DB=/path/to/shared/lifecycle.db

Ambiente Virtual (Recomendado)

# Create a virtual environment for lifecycle-mcp
cd /path/to/lifecycle-mcp
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in the virtual environment
pip install -e .

# Find the venv's lifecycle-mcp command
which lifecycle-mcp  # Copy this path

# Use the full path when adding to Claude
claude mcp add lifecycle /path/to/venv/bin/lifecycle-mcp -e LIFECYCLE_DB=./lifecycle.db

Visualizando o Rastreador

Cada ferramenta retorna texto para um agente transmitir. Para visualizar um rastreador você mesmo, gere uma visualização HTML somente leitura dele:

make viewer                                  # this repository's tracker
make viewer DB=~/work/quire/lifecycle.db     # another project's
make viewer OUT=/tmp/tracker.html            # somewhere other than exports/

Isso grava exports/<project>-tracker.html — um arquivo que abre com duplo clique, em qualquer navegador, em qualquer máquina, sem nada instalado e sem nada buscado na rede. Ele contém:

  • o painel: trabalho bloqueado e aguardando, trabalho concluído e aguardando decisão, o que está pronto para começar, o que precisa de verificação e o que mudou desde a revisão, cada um calculado pelas mesmas definições que as ferramentas do servidor usam
  • cada requisito, tarefa e decisão com todos os campos que possui e seus comentários, pesquisáveis em todos eles
  • os links de cada registro a partir de sua própria extremidade, com cada link saltando para o registro que nomeia

É um instantâneo, não uma visualização ao vivo. Mostra o rastreador como estava quando foi gerado e informa quando isso ocorreu no topo. Execute make viewer novamente para ver alterações posteriores.

É somente leitura. A página não contém banco de dados nem forma de gravar em um; nada feito nela pode alterar um rastreador.

É tão sensível quanto o banco de dados. A página incorpora todo o rastreador como texto simples. Trate-a como lifecycle.db antes de anexá-la ou publicá-la.

make viewer lê o lifecycle.db deste repositório, a menos que DB nomeie outro. Ele não consulta LIFECYCLE_DB: isso frequentemente aponta para um projeto diferente, e um comando que diz que mostra este repositório não deve silenciosamente mostrar outro. Um caminho que não existe é relatado, nunca criado. A saída vai para exports/, que é ignorado pelo git, então gerá-lo nunca aparece em git status.

Referência de Ferramentas MCP

O servidor expõe 23 ferramentas MCP (24 com integração GitHub ativada) em 7 módulos de manipuladores para gerenciamento abrangente do ciclo de vida. Cada ferramenta rejeita campos que não declara, e o erro nomeia o campo. CHANGELOG.md lista ferramentas que foram removidas ou renomeadas, com suas substituições.

Os resultados são texto para o modelo ler. A maioria das ferramentas também retorna os mesmos fatos como dados em structuredContent: ferramentas de criação retornam o novo ID e status, ferramentas de edição os campos alterados e nova revisão, ferramentas de status o status antigo e novo (uma lista de IDs recebe um resultado por ID), e ferramentas de consulta os registros completos. Nenhuma ferramenta declara um outputSchema.

Lista de Ferramentas

Requisitos

  • create_requirement - Criar novos requisitos
  • update_requirement - Editar o conteúdo de um requisito (um motivo é obrigatório em Aprovado ou posterior)
  • update_requirement_status - Mover um ou muitos requisitos através dos estados do ciclo de vida, percorrendo o caminho permitido
  • query_requirements - Pesquisar e filtrar requisitos, incluindo aqueles cujo trabalho está concluído e falta apenas a decisão; os registros correspondentes também retornam como dados estruturados
  • trace_requirement - Rastrear requisito através da implementação

Tarefas

  • create_task - Criar tarefas de implementação a partir de requisitos
  • update_task - Editar o conteúdo de uma tarefa, movê-la para outro pai ou alterar seus requisitos
  • update_task_status - Atualizar o progresso de uma ou muitas tarefas; o comentário em uma movimentação para Bloqueado é mantido como motivo
  • query_tasks - Pesquisar e filtrar tarefas, incluindo aquelas prontas para começar; os registros correspondentes também retornam como dados estruturados
  • sync_github_tasks - Sincronizar uma tarefa, ou todas as tarefas vinculadas, a partir de issues do GitHub (listado apenas quando LIFECYCLE_GITHUB=on)

Decisões de arquitetura

  • create_architecture_decision - Registrar decisões de arquitetura (ADRs)
  • update_architecture - Editar uma decisão de arquitetura Proposta, ou registrar uma emenda datada contra uma Aceita
  • update_architecture_status - Atualizar o status de uma ou muitas decisões de arquitetura; Substituída vem de um link de substituição
  • query_architecture_decisions - Pesquisar e filtrar decisões de arquitetura; os registros correspondentes também retornam como dados estruturados

Qualquer registro (requisito, tarefa ou decisão de arquitetura, por ID)

  • get_details - Detalhes completos de um registro, com seus links e comentários
  • delete_record - Excluir um requisito Rascunho, tarefa Não Iniciada ou decisão de arquitetura Proposta criada por engano
  • add_comment - Comentar em um registro; os comentários aparecem em seus detalhes e histórico

Relacionamentos e histórico

  • create_relationship - Vincular dois registros: dependências, refinamentos, bloqueios, uma tarefa implementando uma decisão de arquitetura, uma decisão mais nova substituindo uma mais antiga, e mais
  • delete_relationship - Remover um link entre dois registros
  • query_relationships - Consultar links: os links de um registro por direção e tipo, ou todos os links como JSON para um grafo
  • get_entity_history - Mostrar como um registro mudou: criação, edições com valores antes e depois, mudanças de status, comentários e exclusão

Status e exportação

  • get_project_status - Painel de saúde do projeto; as métricas também retornam como dados estruturados
  • export_project_documentation - Exportar documentação abrangente em markdown
  • create_architectural_diagrams - Gerar diagramas Mermaid para visualização do projeto

Edição, Exclusão e Histórico

Estas regras se aplicam a update_requirement, update_task, update_architecture e delete_record:

  • Edições acontecem no local. Ferramentas de atualização alteram apenas o conteúdo; movimentações de status permanecem com as ferramentas update_*_status, e os IDs dos registros nunca mudam.
  • Cada mudança é registrada. Cada campo alterado é registrado com seus valores antes e depois, o ator e o motivo. get_entity_history mostra o registro.
  • Revisões protegem contra atualizações perdidas. Cada registro tem uma revisão, mostrada em seus detalhes, que aumenta em um a cada atualização que altera algo. Passe if_revision para que a atualização seja recusada, sem nada gravado, quando o registro mudou desde que você o leu.
  • Requisitos aprovados precisam de um motivo. Editar um requisito em Aprovado ou posterior exige reason. O requisito então aparece como Alterado Desde a Última Revisão em get_details, trace_requirement e get_project_status, listando os campos editados.
  • A próxima mudança de status é o reconhecimento. Não há etapa separada de reconhecimento: a próxima transição de status do requisito limpa o sinalizador, e o comentário dessa transição registra a revisão.
  • Arquitetura decidida não é reescrita. Decisões de arquitetura podem ser editadas apenas enquanto Propostas. Para alterar uma decidida, registre uma nova decisão com create_architecture_decision e vincule-a com create_relationship (supersedes, mais nova para mais antiga), o que move a antiga para Substituída. Para corrigir uma decisão aceita sem mudar a direção — um número que o trabalho posteriormente mediu de forma diferente, por exemplo — passe amendment para update_architecture. Ele registra uma nota datada e atribuída ao lado da decisão e nunca toca no texto da própria decisão, então isso é uma adição à regra, não uma exceção a ela.
  • Exclusão é para enganos. Apenas requisitos Rascunho, tarefas Não Iniciadas e decisões de arquitetura Propostas podem ser excluídos, e apenas quando nada depende deles. Recusas nomeiam os registros bloqueadores. Os links próprios de um registro excluído vão junto, e seu histórico permanece.

get_entity_history

Mostre como um requisito, tarefa ou decisão de arquitetura mudou ao longo do tempo, do mais antigo ao mais recente.

Parâmetros:

  • entity_id (obrigatório): ID do requisito, tarefa ou decisão de arquitetura

Retorna: Criação, edições de campos com valores antes e depois e motivos, mudanças de status, comentários e exclusão. Ainda disponível após o registro ser excluído.

get_details

Detalhes completos de um requisito, tarefa ou decisão de arquitetura. O prefixo do ID (REQ-, TASK-, ADR-) informa ao servidor qual tipo de registro é.

Parâmetros:

  • entity_id (obrigatório): ID do requisito, tarefa ou decisão de arquitetura

Retorna: Os campos do registro, revisão, links (tarefas vinculadas, subtarefas e pai, requisitos vinculados, as tarefas que implementam uma decisão, as decisões que uma tarefa implementa, as decisões que uma decisão substitui ou é substituída, e as tarefas das quais uma tarefa depende ou bloqueia) e comentários. Uma tarefa Bloqueada mostra seu motivo de bloqueio. Um requisito revisado editado desde sua última mudança de status é sinalizado como Alterado Desde a Última Revisão.

delete_record

Excluir um registro criado por engano.

Parâmetros:

  • entity_id (obrigatório): ID do requisito, tarefa ou decisão de arquitetura

Apenas requisitos Rascunho, tarefas Não Iniciadas e decisões de arquitetura Propostas podem ser excluídos. Recusado, nomeando o que o bloqueia, quando:

  • Requisito: tarefas, decisões de arquitetura ou outros requisitos vinculam-se a ele.
  • Tarefa: possui subtarefas, outras tarefas dependem dela, ou está vinculada a uma issue do GitHub.
  • Decisão de arquitetura: outra decisão é substituída por ela, ou registros além de seus próprios links de requisito apontam para ela.

Qualquer coisa além de seu estágio inicial muda de status (Descontinuado, Abandonado, Rejeitado ou Substituído).

add_comment

Comentar em um requisito, tarefa ou decisão de arquitetura.

Parâmetros:

  • entity_id (obrigatório): ID do requisito, tarefa ou decisão de arquitetura
  • comment (obrigatório): O comentário
  • author (opcional): Quem o escreveu (padrão: Usuário MCP)

Retorna: Confirmação. O comentário aparece nos detalhes do registro sob Comentários e em get_entity_history.

Gerenciamento de Requisitos

create_requirement

Criar um novo requisito. Parâmetros:

  • type (obrigatório): Tipo de requisito - "FUNC", "NFUNC", "TECH", "BUS", "INTF"
  • title (obrigatório): Título descritivo
  • priority (obrigatório): Nível de prioridade - "P0", "P1", "P2", "P3"
  • current_state (obrigatório): Estado atual do sistema
  • desired_state (obrigatório): Estado alvo do sistema
  • functional_requirements (opcional): Matriz de requisitos funcionais
  • acceptance_criteria (opcional): Matriz de critérios de aceitação
  • business_value (opcional): Justificativa de negócio
  • risk_level (opcional): Avaliação de risco - "Alto", "Médio", "Baixo"
  • author (opcional): Autor do requisito
  • nonfunctional_requirements (opcional): Matriz de requisitos não funcionais (desempenho, segurança, ...)
  • technical_constraints (opcional): Matriz de restrições técnicas
  • business_rules (opcional): Matriz de regras de negócio
  • validation_metrics (opcional): Matriz de métricas que mostram que o requisito é atendido
  • out_of_scope (opcional): Matriz de itens explicitamente não cobertos

Exemplo:

{
  "type": "FUNC",
  "title": "User Authentication System",
  "priority": "P1",
  "current_state": "No user authentication exists",
  "desired_state": "Secure user login with JWT tokens",
  "functional_requirements": ["Login with email/password", "JWT token generation"],
  "acceptance_criteria": ["User can login successfully", "Token expires after 24 hours"],
  "business_value": "Enables secure user access to protected features",
  "risk_level": "Medium"
}

update_requirement_status

Mover um ou muitos requisitos ao longo do seu ciclo de vida com validação.

Parâmetros:

  • requirement_id: ID do requisito (ex.: "REQ-0001-FUNC-00")
  • requirement_ids: Em vez de requirement_id, uma lista de IDs de requisitos para mover para o mesmo status
  • new_status (obrigatório): Status alvo - "Rascunho", "Em Revisão", "Aprovado", "Arquitetura", "Pronto", "Implementado", "Validado", "Descontinuado"
  • comment (opcional): Comentário de revisão ou justificativa, adicionado uma vez a cada requisito movido

Passe requirement_id ou requirement_ids, não ambos. Cada ID em uma lista se move por conta própria: o resultado lista cada ID, e structuredContent contém results (uma entrada por ID, com error quando recusado), moved e refused. Algumas recusas tornam isso um aviso enquanto os outros IDs ainda se movem; é um erro apenas quando nenhum se moveu.

Quando new_status está a mais de um passo de distância, o requisito percorre o caminho permitido mais curto e cada passo é registrado como sua própria mudança de status: Rascunho → Aprovado passa por Em Revisão, e Aprovado → Validado passa por Pronto e Implementado. Uma movimentação nunca passa por Aprovado ou Validado; esses só podem ser onde termina. As portas se aplicam antes de qualquer mudança, então uma movimentação recusada deixa o requisito onde estava. Resultados de múltiplos passos incluem o path.

Transições de Estado Válidas:

  • Rascunho → Em Revisão, Descontinuado
  • Em Revisão → Rascunho, Aprovado, Descontinuado
  • Aprovado → Arquitetura, Pronto, Descontinuado
  • Arquitetura → Pronto, Aprovado
  • Pronto → Implementado, Descontinuado
  • Implementado → Validado, Pronto
  • Validado → Descontinuado

query_requirements

Pesquisar e filtrar requisitos por vários critérios.

Parâmetros:

  • status (opcional): Filtrar por status
  • priority (opcional): Filtrar por nível de prioridade
  • type (opcional): Filtrar por tipo de requisito
  • search_text (opcional): Pesquisa de texto no título e estado desejado
  • work_complete (opcional): true para os requisitos cujas tarefas vinculadas estão todas Concluídas, mas que não alcançaram Implementado - o trabalho está feito e apenas a decisão está faltando

trace_requirement

Rastrear um requisito ao longo do seu ciclo de vida completo de implementação.

Parâmetros:

  • requirement_id (obrigatório): ID do requisito

Retorna: Rastreamento completo incluindo detalhes do requisito, tarefas de implementação e decisões de arquitetura.

update_requirement

Editar o conteúdo de um requisito no lugar. Veja Edição, Exclusão e Histórico para as regras.

Parâmetros:

  • requirement_id (obrigatório): ID do requisito
  • title, priority, risk_level, current_state, desired_state, functional_requirements, acceptance_criteria, business_value, nonfunctional_requirements, technical_constraints, business_rules, validation_metrics, out_of_scope (pelo menos um): Novos valores, com os mesmos tipos que em create_requirement
  • reason (obrigatório em Aprovado ou posterior): Por que a mudança é feita
  • actor (opcional): Quem faz a mudança (padrão: Usuário MCP)
  • if_revision (opcional): Recusar a edição a menos que o requisito ainda esteja nesta revisão

Exemplo:

{
  "requirement_id": "REQ-0001-FUNC-00",
  "acceptance_criteria": ["User can login successfully", "Token expires after 1 hour"],
  "reason": "Security review shortened token lifetime",
  "if_revision": 2
}

Gerenciamento de Tarefas

create_task

Criar tarefas de implementação vinculadas a requisitos.

Parâmetros:

  • requirement_ids (obrigatório): Matriz de IDs de requisitos para vincular
  • title (obrigatório): Título da tarefa
  • priority (obrigatório): Nível de prioridade - "P0", "P1", "P2", "P3"
  • effort (opcional): Estimativa de esforço - "XS", "S", "M", "L", "XL"
  • user_story (opcional): Descrição da história de usuário
  • acceptance_criteria (opcional): Matriz de critérios de aceitação
  • parent_task_id (opcional): Tarefa pai para subtarefas
  • assignee (opcional): Responsável pela tarefa
  • implementation_plan (opcional): Matriz de etapas de implementação
  • test_plan (opcional): Matriz de testes ou verificações a executar
  • definition_of_done (opcional): Matriz de condições para considerar a tarefa concluída

Exemplo:

{
  "requirement_ids": ["REQ-0001-FUNC-00"],
  "title": "Implement JWT token generation",
  "priority": "P1",
  "effort": "M",
  "user_story": "As a developer, I need JWT token generation so users can authenticate securely",
  "acceptance_criteria": ["Generate JWT with user claims", "Token expires in 24 hours"],
  "assignee": "john.doe@company.com"
}

update_task_status

Atualizar o progresso e a atribuição da tarefa.

Parâmetros:

  • task_id: ID da tarefa (ex.: "TASK-0001-00-00")
  • task_ids: Em vez de task_id, uma lista de IDs de tarefas para mover para o mesmo status, com um resultado por ID como em update_requirement_status
  • new_status (obrigatório): Novo status - "Não Iniciado", "Em Andamento", "Bloqueado", "Concluído", "Abandonado"
  • comment (opcional): Comentário de atualização de status. Em uma movimentação para Bloqueado, é mantido como o motivo do bloqueio da tarefa até que a tarefa saia de Bloqueado; mover uma tarefa Bloqueada para Bloqueado novamente sem comentário mantém o motivo
  • assignee (opcional): Novo responsável
  • commit (opcional): O commit por trás desta movimentação, mantido na tarefa
  • evidence (opcional): O resultado de teste ou verificação por trás desta movimentação, mantido na tarefa

commit e evidence permanecem na tarefa após a movimentação: uma mudança de status posterior que os omita os deixa no lugar, e passar novos valores os substitui. Ambos aparecem nos detalhes da tarefa e na documentação exportada da tarefa, então o raciocínio por trás de uma tarefa concluída sobrevive à transferência.

query_tasks

Pesquisar e filtrar tarefas por vários critérios.

Parâmetros:

  • status (opcional): Filtrar por status
  • priority (opcional): Filtrar por nível de prioridade
  • assignee (opcional): Filtrar por responsável
  • requirement_id (opcional): Filtrar por requisito vinculado
  • ready (opcional): true para tarefas Não Iniciadas cujas dependências estão todas Concluídas, maior prioridade primeiro. Uma tarefa espera nas tarefas das quais depende ou que exige, e nas tarefas que a bloqueiam

Filtros se combinam.

Quando ready não encontra nada, a resposta diz qual é o caso em vez de que nenhuma tarefa foi encontrada: nenhuma tarefa restante, toda tarefa restante está esperando (com quantas estão Bloqueadas e quantas esperam em dependências), ou o único trabalho iniciável já está Em Andamento.

sync_github_tasks

Sincronizar tarefas a partir de suas issues vinculadas do GitHub, com detecção de conflitos. Listado apenas quando LIFECYCLE_GITHUB=on.

Parâmetros:

  • task_id (opcional): Tarefa para sincronizar com sua issue vinculada do GitHub; omita para sincronizar toda tarefa vinculada a uma issue

Retorna: Status da sincronização e quaisquer atualizações aplicadas a partir dos dados da issue do GitHub.

update_task

Editar o conteúdo de uma tarefa, movê-la sob outro pai ou alterar os requisitos que ela implementa. O ID da tarefa nunca muda.

Parâmetros:

  • task_id (obrigatório): ID da tarefa
  • title, priority, effort, user_story, acceptance_criteria, assignee, implementation_plan, test_plan, definition_of_done (opcional): Novos valores, com os mesmos tipos que em create_task
  • parent_task_id (opcional): Nova tarefa pai; uma string vazia a torna uma tarefa de nível superior. Uma tarefa não pode se tornar seu próprio pai ou se mover sob uma de suas subtarefas
  • requirement_ids (opcional): Substitui os requisitos que a tarefa implementa; requisitos sendo adicionados devem ser aprovados, como em create_task
  • reason, actor, if_revision (opcional): Como em update_requirement

Passe pelo menos um campo para alterar. Mudanças não são enviadas para uma issue vinculada do GitHub.

Gerenciamento de Arquitetura

create_architecture_decision

Registrar decisões de arquitetura (ADRs) com contexto completo.

Parâmetros:

  • requirement_ids (obrigatório): Matriz de IDs de requisitos abordados
  • title (obrigatório): Título da decisão
  • context (obrigatório): Contexto e histórico da decisão
  • decision (obrigatório): A decisão tomada
  • consequences (opcional): Objeto de consequências da decisão
  • decision_drivers (opcional): Matriz de fatores que impulsionam a decisão
  • considered_options (opcional): Matriz de alternativas consideradas
  • authors (opcional): Matriz de autores da decisão
  • deciders (opcional): Matriz de pessoas que tomaram a decisão
  • implementation_notes (opcional): Notas para implementar a decisão
  • validation_criteria (opcional): Matriz de verificações que mostram que a decisão funciona
  • risk_assessment (opcional): Matriz de riscos, cada um com probabilidade, impacto e mitigação

Exemplo:

{
  "requirement_ids": ["REQ-0001-FUNC-00"],
  "title": "Use JWT for authentication tokens",
  "context": "Need secure, stateless authentication for API access",
  "decision": "Implement JWT tokens with RS256 signing",
  "consequences": {
    "positive": ["Stateless authentication", "Industry standard"],
    "negative": ["Token size overhead", "Key management complexity"]
  },
  "decision_drivers": ["Security requirements", "Scalability needs"],
  "considered_options": ["Session cookies", "OAuth2", "JWT tokens"]
}

update_architecture_status

Atualizar o status de uma ou muitas decisões de arquitetura.

Parâmetros:

  • architecture_id: ID da arquitetura (ex.: "ADR-0001")
  • architecture_ids: Em vez de architecture_id, uma lista de IDs de decisões para mover para o mesmo status, com um resultado por ID como em update_requirement_status
  • new_status (obrigatório): Novo status - "Proposto", "Aceito", "Rejeitado", "Descontinuado", "Substituído", "Rascunho", "Em Revisão", "Aprovado", "Implementado"
  • comment (opcional): Comentário de mudança de status

Substituído vem de um link: create_relationship com a decisão mais nova como source_id, a mais antiga como target_id e relationship_type supersedes move a mais antiga para Substituído e define seu superseded_by. Esta ferramenta recusa Substituído sem esse link, e recusa mover uma decisão substituída para outro lugar até que o link seja excluído.

query_architecture_decisions

Pesquisar e filtrar decisões de arquitetura por vários critérios.

Parâmetros:

  • status (opcional): Filtrar por status
  • type (opcional): Filtrar por tipo (ADR, TDD, INTG)
  • requirement_id (opcional): Filtrar por requisito vinculado
  • search_text (opcional): Pesquisa de texto no título e contexto

update_architecture

Editar o conteúdo de uma decisão de arquitetura enquanto ela está Proposta. Decisões em qualquer outro status são recusadas: registre uma nova decisão com create_architecture_decision e vincule-a à antiga com um relacionamento supersedes, o que move a antiga para Substituído.

Uma decisão Aceita pode, em vez disso, ser emendada: amendment registra uma correção datada e atribuída, carregando seu reason, contra a decisão. Nada sobre a decisão é editado - seu texto, revisão e carimbo de data/hora são deixados exatamente como estavam - e a emenda é armazenada como um evento de ciclo de vida, então get_entity_history a mostra como seu próprio tipo de entrada. Emendas são renderizadas diretamente abaixo da decisão que corrigem em get_details e na documentação de arquitetura exportada, marcadas como correções posteriores, então um leitor não pode absorver o texto desatualizado sem vê-las. Passe amendment sozinho; emendar uma decisão Proposta é recusado, apontando para a edição que deveria ser. Parâmetros:

  • architecture_id (obrigatório): ID da arquitetura
  • title, context, decision, consequences, decision_drivers, considered_options, authors, deciders, implementation_notes, validation_criteria, risk_assessment (pelo menos um, ao editar): Novos valores, com os mesmos tipos de create_architecture_decision
  • amendment (em vez dos campos acima): Uma correção datada para uma decisão Aceita
  • reason, actor, if_revision (opcional): Como em update_requirement. reason é transportado na emenda

Monitoramento de Projeto

get_project_status

Obtenha métricas abrangentes de saúde do projeto e painéis.

Parâmetros:

  • include_blocked (opcional): Incluir análise de itens bloqueados (padrão: true)

Retorna: Painel com visão geral de requisitos, estatísticas de tarefas, percentuais de conclusão e itens bloqueados: cada tarefa Bloqueada com seu motivo, e cada tarefa ou requisito ainda aguardando uma dependência com o que está aguardando. structuredContent contém as métricas e, quando include_blocked está ativo, os mesmos itens sob blocked.

Ferramentas de Exportação de Documentação

export_project_documentation

Exporte documentação abrangente do projeto em formato markdown estruturado.

Parâmetros:

  • project_name (opcional): Nome do projeto usado nos nomes de arquivo (padrão: "project")
  • include_requirements (opcional): Incluir documentação de requisitos (padrão: true)
  • include_tasks (opcional): Incluir documentação de tarefas (padrão: true)
  • include_architecture (opcional): Incluir documentação de arquitetura (padrão: true)
  • output_directory (opcional): Diretório para salvar os arquivos exportados (padrão: ".")

Retorna: Lista de arquivos exportados com seus caminhos.

Arquivos Gerados:

  • {project_name}-requirements.md - Documentação completa de requisitos agrupada por tipo
  • {project_name}-tasks.md - Documentação de tarefas agrupada por status, com requisitos vinculados, o commit e a evidência de cada tarefa, e seus comentários
  • {project_name}-architecture.md - Decisões de arquitetura com contexto, decisões e consequências

Exemplo:

{
  "project_name": "ecommerce-platform",
  "include_requirements": true,
  "include_tasks": true,
  "include_architecture": true,
  "output_directory": "./docs"
}

create_architectural_diagrams

Gere diagramas Mermaid para visualização da arquitetura do projeto e relacionamentos.

Parâmetros:

  • diagram_type (opcional): Tipo de diagrama - "requirements", "tasks", "architecture", "full_project", "dependencies" (padrão: "full_project")
  • limit (opcional): Limite cada tipo de registro. A resposta informa o que foi desenhado e o que o limite deixou de fora; sem ele, nada é limitado
  • requirement_ids (opcional): Matriz de IDs específicos de requisitos a incluir
  • include_relationships (opcional): Incluir setas de relacionamento nos diagramas (padrão: true)
  • output_format (opcional): Formato de saída - "mermaid", "markdown_with_mermaid" (padrão: "mermaid")

Retorna: Código do diagrama Mermaid ou diagrama envolvido em markdown.

Tipos de Diagrama:

  • requirements: Requisitos agrupados por tipo, com arestas de pai e dependência, em cores de status
  • tasks: Tarefas com arestas de subtarefa, dependência e bloqueio, em cores de status
  • architecture: Decisões, o que elas substituem e os requisitos que cada uma aborda
  • full_project: O grafo completo - requisitos, tarefas e decisões com todos os links entre eles
  • dependencies: As tarefas que aguardam outras tarefas, nomeadas em vez de IDs simples

Cada aresta lê origem para destino com um rótulo, então uma dependência aponta para o que está aguardando. Requisitos e decisões obsoletos são omitidos, e a resposta informa quantos foram. Cada tipo grava um arquivo, {diagram_type}-diagram.mmd ou .md, sobrescrito a cada renderização.

Cores de Status:

  • Requisitos: Rascunho (vermelho), Em Revisão (laranja), Aprovado (azul), Pronto (verde), etc.
  • Tarefas: Não Iniciada (vermelho), Em Andamento (laranja), Bloqueada (vermelho escuro), Concluída (verde), etc.
  • Arquitetura: Proposta (laranja), Aceita (verde), Rejeitada (vermelho), Obsoleta (cinza), etc.

Exemplo:

{
  "diagram_type": "requirements",
  "include_relationships": true,
  "output_format": "markdown_with_mermaid"
}

Esquema do Banco de Dados

O servidor mantém um banco de dados SQLite abrangente com as seguintes entidades principais:

  • Requisitos: Entidade central com estados de ciclo de vida (Rascunho → Em Revisão → Aprovado → Arquitetura → Pronto → Implementado → Validado → Obsoleto)
  • Tarefas: Itens de trabalho de implementação com estrutura hierárquica (formato TASK-XXXX-YY-ZZ)
  • Arquitetura: ADRs e documentos de design técnico
  • Relacionamentos: Links muitos-para-muitos entre requisitos, tarefas e arquitetura
  • Eventos: Registro automático de eventos de ciclo de vida e mudanças de status
  • Comentários: Notas sobre requisitos, tarefas e decisões de arquitetura, adicionadas com add_comment ou o comment de uma mudança de status

IDs Curtos

Em qualquer lugar onde uma ferramenta aceita um ID de registro, o preenchimento com zeros e a versão final podem ser omitidos:

DigitadoResolve para
REQ-12-FUNCREQ-0012-FUNC-00
TASK-12TASK-0012-00-00
TASK-12-1TASK-0012-01-00
ADR-4ADR-0004

A forma curta de um requisito mantém seu tipo, porque os números de requisitos se repetem entre tipos: REQ-12 sozinho pode significar quatro registros diferentes. IDs completos armazenados sempre funcionam. Um alias que não corresponde a nada é recusado como desconhecido, e um que corresponde a vários é recusado nomeando os candidatos, então uma ferramenta nunca age com base em suposição. IDs armazenados nunca mudam; isso é apenas uma forma de entrada.

Chamadas Recusadas

Uma chamada cujos argumentos não correspondem ao esquema da ferramenta é recusada antes que qualquer coisa seja gravada, nomeando o campo com problema. Quando o parâmetro recusado tem um vizinho próximo no mesmo esquema que teria aceitado o valor, a mensagem o nomeia: passar uma lista para requirement_id responde que requirement_ids aceita uma matriz e aceita o que você passou. A sugestão é lida do próprio esquema da ferramenta, então um novo par singular/plural é coberto no dia em que é declarado.

Chamadas recusadas chegam ao registro de chamadas como qualquer outra quando LIFECYCLE_CALL_LOG está definido, então os totais de uma sessão cobrem as chamadas que um cliente errou, em vez de apenas aquelas que chegaram a um manipulador.

Formatos de ID de Entidade

  • Requisitos: REQ-XXXX-TYPE-VV (ex.: REQ-0001-FUNC-00)
  • Tarefas: TASK-XXXX-YY-ZZ (ex.: TASK-0001-00-00)
  • Arquitetura: ADR-XXXX (ex.: ADR-0001)

Variáveis de Ambiente

  • LIFECYCLE_DB: Caminho para o arquivo do banco de dados SQLite (padrão: "./lifecycle.db")
  • LIFECYCLE_GITHUB: Defina como on para criar e sincronizar uma issue do GitHub para cada tarefa (padrão: desativado). Requer uma CLI gh autenticada e um remote origin do github.com no diretório de trabalho do servidor. Quando desativado, o servidor nunca executa gh ou git, e a ferramenta sync_github_tasks não é listada.
  • LIFECYCLE_RULES: Quão estritamente movimentos de status arriscados são tratados - off, warn ou enforce (padrão: warn). Qualquer outra coisa volta para warn.
  • LIFECYCLE_STALE_AFTER: Quantos dias um requisito pode ficar sem verificação antes que get_project_status o persiga (padrão: 14). 0 persegue cada requisito assim que é escrito. Qualquer coisa que não seja um número de dias volta ao padrão.
  • LIFECYCLE_CALL_LOG: Caminho para um arquivo onde o servidor anexa uma linha JSON por chamada de ferramenta: nome da ferramenta, nomes dos argumentos (não valores), duração, se falhou e tamanho da resposta. Desativado por padrão. Cada chamada que o servidor recebe é registrada, incluindo uma que seu esquema recusou e uma que nomeia uma ferramenta que não existe: essas carregam error_kind (validation, unknown_tool) e a regra e o parâmetro pelos quais foram recusadas, então os totais de uma sessão cobrem as chamadas que um cliente errou. scripts/tool_usage_report.py resume esses registros.

Escrevendo Requisitos

O servidor oferece um prompt MCP, capture_requirement, listado sob prompts/list. É um guia para escrever um requisito bem formado que seu próprio modelo preenche e depois passa para create_requirement em uma única chamada; ele aceita um argumento opcional about carregando o que a pessoa disse em suas próprias palavras. Nada é mantido no servidor entre chamadas.

Novos registros também indicam quando são superficiais para seu tipo: um requisito sem acceptance_criteria, um requisito NFUNC sem validation_metrics, uma tarefa P0 ou P1 sem test_plan. Essas são regras de fluxo de trabalho, então avisam por padrão, recusam sob LIFECYCLE_RULES=enforce e ficam silenciosas sob off.

Os detalhes de um requisito mostram quando alguém o verificou pela última vez contra a realidade, e get_project_status lista os que valem a pena reler sob Necessita Verificação: aqueles cujo conteúdo mudou após a última verificação, e aqueles que ninguém verificou por mais de LIFECYCLE_STALE_AFTER dias. Escrever um requisito conta como a primeira verificação, e depois comentar sobre ele ou mover seu status também conta, então nada é perseguido no dia em que foi escrito. A linha declara os dois momentos que mantém - quando o conteúdo mudou e quando foi verificado pela última vez - e nunca afirma saber o momento em que o requisito ficou desatualizado.

Quando todas as tarefas que implementam um requisito estão Concluídas, mas o requisito não alcançou Implementado, o trabalho está feito e apenas a decisão está faltando. get_project_status nomeia esses requisitos sob Trabalho Concluído, Decisão Pendente, e query_requirements os encontra com work_complete. Nada se move sozinho: o rastreador solicita e a pessoa decide.

Regras de Fluxo de Trabalho

Um movimento de status pode ser arriscado sem estar errado. LIFECYCLE_RULES decide o que acontece então:

  • warn (padrão): o movimento acontece exatamente como hoje, e a resposta diz por que foi arriscado, no texto e em structuredContent sob warnings - por registro para uma lista de IDs.
  • enforce: o movimento é recusado antes que qualquer coisa seja gravada, nomeando o que o bloqueia.
  • off: nada é verificado.

As regras:

  • Dependências não concluídas: iniciar ou concluir uma tarefa cujas dependências não estão todas Concluídas as nomeia. Uma dependência abandonada é nomeada separadamente, com as duas saídas: remover o link com delete_relationship, ou abandonar a tarefa que aguarda também.
  • Subtarefas abertas: concluir uma tarefa enquanto uma subtarefa não está nem Concluída nem Abandonada nomeia as subtarefas abertas.
  • Pulos e reaberturas: concluir uma tarefa que nunca foi iniciada ou ainda está Bloqueada, e reabrir uma tarefa Concluída, cada uma diz isso.
  • O portão Implementado: um requisito alcançando Implementado enquanto as tarefas que o implementam estão abertas as nomeia.
  • Movimentos de decisão: uma decisão de arquitetura se movendo para fora de seu vocabulário diz onde esse status normalmente vai. Os status de ADR e a cadeia TDD são conjuntos separados.

Três regras estão sempre ativas, qualquer que seja o modo, porque protegem o que o servidor mantém por si só: um requisito não pode ser Validado enquanto uma tarefa vinculada está aberta, Superseded precisa de um link supersedes, e o status de um requisito ainda segue seu mapa de transição.

Solução de Problemas

Problemas de Conexão

"MCP error -32000: Connection closed"

O servidor saiu ou escreveu algo diferente de mensagens de protocolo no stdout. Para verificar uma instalação:

python3 scripts/mcp_handshake_smoke.py lifecycle-mcp

Isso inicia o servidor duas vezes contra um banco de dados temporário e relata se o handshake MCP é bem-sucedido com stdout limpo. Se falhar:

  1. Reinstale para que o SDK MCP fixado (mcp[cli]>=1.10,<2) seja usado:

    uv tool install --force .

  2. Re-adicione o servidor MCP:

    claude mcp add lifecycle lifecycle-mcp

  3. Verifique se o servidor inicia sem erros:

    lifecycle-mcp

Servidor Não Encontrado

Se o comando lifecycle-mcp não for encontrado após a instalação:

  1. Verifique se a instalação foi concluída com sucesso
  2. Verifique se o ponto de entrada está registrado em pyproject.toml
  3. Tente reinstalar com pip install -e .

Problemas de Banco de Dados

Erros de Bloqueio do Banco de Dados

Se você vir erros de bloqueio do banco de dados, garanta que apenas uma instância do servidor esteja em execução e que o arquivo do banco de dados tenha permissões adequadas.

Inicialização do Esquema

O esquema do banco de dados é criado automaticamente na primeira execução. Se você precisar redefinir o banco de dados, simplesmente exclua o arquivo SQLite (padrão: lifecycle.db).

Desenvolvimento

Usando uv (Recomendado)

# Install dependencies
uv sync

# Run the server directly
uv run server.py

# Test with Claude Code
claude mcp add lifecycle $(which uv) -- --directory $(pwd) run server.py

Usando pip (Tradicional)

# Install in development mode
pip install -e .

# Run the server
lifecycle-mcp

# Test with Claude Code
claude mcp add lifecycle lifecycle-mcp

Criando Extensão de Desktop (.dxt)

Para criar um pacote de Extensão de Desktop para instalação com um clique:

# Build the .dxt file
make build-dxt
# or
python build_dxt.py

Isso cria lifecycle-mcp-1.0.0.dxt, que os usuários podem clicar duas vezes para instalar no Claude Desktop.