Lifecycle MCP Server

Un servidor MCP para gestionar el ciclo de vida del desarrollo de software, con soporte para una base de datos SQLite externa opcional.

GitHub
39

Documentación

Servidor Lifecycle MCP

Un servidor de Protocolo de Contexto de Modelo (MCP) para la gestión integral del ciclo de vida del software. Este servidor proporciona un seguimiento estructurado de requisitos, tareas y decisiones de arquitectura a través de una base de datos SQLite con trazabilidad completa y gestión automatizada de estados.

Características

  • Gestión de Requisitos: Cree y gestione requisitos de software con validación y seguimiento del ciclo de vida
  • Gestión de Tareas: Realice un seguimiento de las tareas de implementación con estructura jerárquica y estimación de esfuerzo
  • Decisiones de Arquitectura: Registre ADR (Registros de Decisiones de Arquitectura) con contexto completo
  • Paneles de Proyecto: Métricas de salud del proyecto en tiempo real e informes de estado
  • Trazabilidad de Requisitos: Trazabilidad completa desde los requisitos hasta la implementación
  • Validación de Estados: Validación automática de las transiciones de estados del ciclo de vida
  • Edición Segura e Historial: Edite registros en el lugar con historial por campo, razones para requisitos aprobados y comprobaciones de revisión; elimine registros creados por error
  • Seguimiento de Relaciones: Relaciones de muchos a muchos entre requisitos, tareas y arquitectura

Inicio 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!

Opciones de Instalación

Requisitos Previos (Opcional)

Si desea utilizar uv (gestor de paquetes de Python más rápido):

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

# Or with homebrew
brew install uv

Clonar el Repositorio

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

Uso con Claude Code

Para ejemplos y escenarios detallados, consulte USAGE_EXAMPLES.md.

Opción 1: Instalación Global (Recomendada para Múltiples Proyectos)

Instale el servidor globalmente para que pueda usarse desde cualquier proyecto:

# 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 proyecto obtiene su propio archivo de base de datos en su directorio.

Opción 2: Ejecutar desde el Código Fuente con uv

Si prefiere no 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

Opción 3: Ejecución Directa con Python

Para máxima compatibilidad:

# 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

Configuración Manual

También puede editar manualmente su archivo de configuración de 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"
      }
    }
  }
}

Buenas Prácticas

Ubicación de la Base de Datos

  • Cada proyecto debe tener su propio archivo lifecycle.db
  • Use LIFECYCLE_DB=./lifecycle.db para crear la base de datos en el proyecto actual
  • O use una ruta absoluta para una base de datos compartida: LIFECYCLE_DB=/path/to/shared/lifecycle.db

Entorno 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

Visualización del Seguimiento

Cada herramienta devuelve texto para que un agente lo transmita. Para ver un seguimiento usted mismo, genere una vista HTML de solo lectura:

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/

Esto escribe exports/<project>-tracker.html — un archivo que se abre con doble clic, en cualquier navegador, en cualquier máquina, sin nada instalado y sin obtener nada de la red. Contiene:

  • el panel: trabajo bloqueado y en espera, trabajo completado y pendiente de decisión, qué está listo para comenzar, qué necesita verificación y qué cambió desde la revisión, cada uno calculado con las mismas definiciones que usan las herramientas del servidor
  • cada requisito, tarea y decisión con cada campo que contiene y sus comentarios, buscable en todos ellos
  • los enlaces de cada registro desde su propio extremo, con cada enlace saltando al registro que nombra

Es una instantánea, no una vista en vivo. Muestra el seguimiento tal como estaba cuando se generó y dice cuándo fue eso en la parte superior. Ejecute make viewer nuevamente para ver cambios posteriores.

Es de solo lectura. La página no contiene base de datos ni forma de escribir en una; nada hecho en ella puede cambiar un seguimiento.

Es tan sensible como la base de datos. La página incrusta todo el seguimiento como texto plano. Trátelo como lifecycle.db antes de adjuntarlo o publicarlo.

make viewer lee el lifecycle.db de este repositorio a menos que DB nombre otro. No consulta LIFECYCLE_DB: eso a menudo apunta a un proyecto diferente, y un comando que dice mostrar este repositorio no debería mostrar silenciosamente otro. Una ruta que no existe se informa, nunca se crea. La salida termina en exports/, que está en gitignore, por lo que generarla nunca aparece en git status.

Referencia de Herramientas MCP

El servidor expone 23 herramientas MCP (24 con integración de GitHub activada) en 7 módulos de manejo para la gestión integral del ciclo de vida. Cada herramienta rechaza campos que no declara, y el error nombra el campo. CHANGELOG.md enumera las herramientas que fueron eliminadas o renombradas, con sus reemplazos.

Los resultados son texto para que el modelo los lea. La mayoría de las herramientas también devuelven los mismos hechos como datos en structuredContent: las herramientas de creación devuelven el nuevo ID y estado, las de edición los campos cambiados y la nueva revisión, las de estado el estado anterior y nuevo (una lista de IDs obtiene un resultado por ID), y las de consulta los registros completos. Ninguna herramienta declara un outputSchema.

Lista de Herramientas

Requisitos

  • create_requirement - Crear nuevos requisitos
  • update_requirement - Editar el contenido de un requisito (se requiere una razón en Aprobado o posterior)
  • update_requirement_status - Mover uno o muchos requisitos a través de los estados del ciclo de vida, avanzando por la ruta permitida
  • query_requirements - Buscar y filtrar requisitos, incluidos aquellos cuyo trabajo está hecho y solo falta la decisión; los registros coincidentes también vuelven como datos estructurados
  • trace_requirement - Trazar requisito a través de la implementación

Tareas

  • create_task - Crear tareas de implementación a partir de requisitos
  • update_task - Editar el contenido de una tarea, moverla a otro padre o cambiar sus requisitos
  • update_task_status - Actualizar el progreso de una o muchas tareas; el comentario en un movimiento a Bloqueado se conserva como la razón
  • query_tasks - Buscar y filtrar tareas, incluidas las listas para comenzar; los registros coincidentes también vuelven como datos estructurados
  • sync_github_tasks - Sincronizar una tarea, o cada tarea vinculada, desde problemas de GitHub (listado solo cuando LIFECYCLE_GITHUB=on)

Decisiones de arquitectura

  • create_architecture_decision - Registrar decisiones de arquitectura (ADR)
  • update_architecture - Editar una decisión de arquitectura Propuesta, o registrar una enmienda fechada contra una Aceptada
  • update_architecture_status - Actualizar el estado de una o muchas decisiones de arquitectura; Superada proviene de un enlace de supera
  • query_architecture_decisions - Buscar y filtrar decisiones de arquitectura; los registros coincidentes también vuelven como datos estructurados

Cualquier registro (requisito, tarea o decisión de arquitectura, por ID)

  • get_details - Detalles completos de un registro, con sus enlaces y comentarios
  • delete_record - Eliminar un requisito Borrador, tarea No Iniciada o decisión de arquitectura Propuesta creada por error
  • add_comment - Comentar sobre un registro; los comentarios aparecen en sus detalles e historial

Relaciones e historial

  • create_relationship - Vincular dos registros: dependencias, refinamientos, bloqueos, una tarea que implementa una decisión de arquitectura, una decisión más nueva que supera a una más antigua, y más
  • delete_relationship - Eliminar un enlace entre dos registros
  • query_relationships - Consultar enlaces: los enlaces de un registro por dirección y tipo, o cada enlace como JSON para un gráfico
  • get_entity_history - Mostrar cómo cambió un registro: creación, ediciones con valores antes y después, cambios de estado, comentarios y eliminación

Estado y exportación

  • get_project_status - Panel de salud del proyecto; las métricas también vuelven como datos estructurados
  • export_project_documentation - Exportar documentación integral en markdown
  • create_architectural_diagrams - Generar diagramas Mermaid para visualización de proyectos

Edición, Eliminación e Historial

Estas reglas se aplican a update_requirement, update_task, update_architecture y delete_record:

  • Las ediciones ocurren en el lugar. Las herramientas de actualización cambian solo el contenido; los movimientos de estado permanecen con las herramientas update_*_status, y los IDs de registro nunca cambian.
  • Cada cambio se registra. Cada campo cambiado se registra con sus valores antes y después, el actor y la razón. get_entity_history muestra el registro.
  • Las revisiones protegen contra actualizaciones perdidas. Cada registro tiene una revisión, mostrada en sus detalles, que aumenta en uno con cada actualización que cambia algo. Pase if_revision para que la actualización sea rechazada, sin escribir nada, cuando el registro ha cambiado desde que lo leyó.
  • Los requisitos aprobados necesitan una razón. Editar un requisito en Aprobado o posterior requiere reason. El requisito entonces se muestra como Cambiado Desde la Última Revisión en get_details, trace_requirement y get_project_status, enumerando los campos editados.
  • El siguiente cambio de estado es el reconocimiento. No hay un paso de reconocimiento separado: la siguiente transición de estado del requisito limpia la marca, y el comentario de esa transición registra la revisión.
  • La arquitectura decidida no se reescribe. Las decisiones de arquitectura solo se pueden editar mientras están Propuestas. Para cambiar una decidida, registre una nueva decisión con create_architecture_decision y vincúlela con create_relationship (supersedes, de más nueva a más antigua), lo que mueve la anterior a Superada. Para corregir una decisión aceptada sin cambiar la dirección — un número que el trabajo luego midió diferente, por ejemplo — pase amendment a update_architecture. Registra una nota fechada y atribuida junto a la decisión y nunca toca el texto propio de la decisión, por lo que esto es una adición a la regla más que una excepción a ella.
  • Eliminar es para errores. Solo los requisitos Borrador, las tareas No Iniciadas y las decisiones de arquitectura Propuestas se pueden eliminar, y solo cuando nada depende de ellas. Los rechazos nombran los registros bloqueantes. Los enlaces propios de un registro eliminado van con él, y su historial permanece.

get_entity_history

Muestre cómo un requisito, tarea o decisión de arquitectura cambió con el tiempo, del más antiguo al más reciente.

Parámetros:

  • entity_id (obligatorio): ID de requisito, tarea o decisión de arquitectura

Devuelve: Creación, ediciones de campos con valores antes y después y razones, cambios de estado, comentarios y eliminación. Aún disponible después de que el registro sea eliminado.

get_details

Detalles completos de un requisito, tarea o decisión de arquitectura. El prefijo del ID (REQ-, TASK-, ADR-) le dice al servidor qué tipo de registro es.

Parámetros:

  • entity_id (obligatorio): ID de requisito, tarea o decisión de arquitectura

Devuelve: Los campos del registro, revisión, enlaces (tareas vinculadas, subtareas y padre, requisitos vinculados, las tareas que implementan una decisión, las decisiones que una tarea implementa, las decisiones que una decisión supera o por las que es superada, y las tareas de las que una tarea depende o bloquea) y comentarios. Una tarea Bloqueada muestra su razón de bloqueo. Un requisito revisado editado desde su último cambio de estado está marcado como Cambiado Desde la Última Revisión.

delete_record

Elimine un registro creado por error.

Parámetros:

  • entity_id (obligatorio): ID de requisito, tarea o decisión de arquitectura

Solo los requisitos Borrador, las tareas No Iniciadas y las decisiones de arquitectura Propuestas se pueden eliminar. Rechazado, nombrando qué lo bloquea, cuando:

  • Requisito: tareas, decisiones de arquitectura u otros requisitos enlazan a él.
  • Tarea: tiene subtareas, otras tareas dependen de ella, o está vinculada a un problema de GitHub.
  • Decisión de arquitectura: otra decisión es superada por ella, o registros distintos de sus propios enlaces de requisito apuntan a ella.

Cualquier cosa más allá de su etapa temprana cambia de estado en su lugar (Obsoleto, Abandonado, Rechazado o Superado).

add_comment

Comente sobre un requisito, tarea o decisión de arquitectura.

Parámetros:

  • entity_id (obligatorio): ID de requisito, tarea o decisión de arquitectura
  • comment (obligatorio): El comentario
  • author (opcional): Quién lo escribió (predeterminado: Usuario MCP)

Devuelve: Confirmación. El comentario aparece en los detalles del registro bajo Comentarios y en get_entity_history.

Gestión de Requisitos

create_requirement

Cree un nuevo requisito. Parámetros:

  • type (obligatorio): Tipo de requisito - "FUNC", "NFUNC", "TECH", "BUS", "INTF"
  • title (obligatorio): Título descriptivo
  • priority (obligatorio): Nivel de prioridad - "P0", "P1", "P2", "P3"
  • current_state (obligatorio): Estado actual del sistema
  • desired_state (obligatorio): Estado objetivo del sistema
  • functional_requirements (opcional): Matriz de requisitos funcionales
  • acceptance_criteria (opcional): Matriz de criterios de aceptación
  • business_value (opcional): Justificación de negocio
  • risk_level (opcional): Evaluación de riesgos - "Alto", "Medio", "Bajo"
  • author (opcional): Autor del requisito
  • nonfunctional_requirements (opcional): Matriz de requisitos no funcionales (rendimiento, seguridad, ...)
  • technical_constraints (opcional): Matriz de restricciones técnicas
  • business_rules (opcional): Matriz de reglas de negocio
  • validation_metrics (opcional): Matriz de métricas que demuestran que el requisito se cumple
  • out_of_scope (opcional): Matriz de elementos explícitamente no cubiertos

Ejemplo:

{
  "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

Mueve uno o varios requisitos a lo largo de su ciclo de vida con validación.

Parámetros:

  • requirement_id: ID del requisito (p. ej., "REQ-0001-FUNC-00")
  • requirement_ids: En lugar de requirement_id, una lista de IDs de requisitos para mover al mismo estado
  • new_status (obligatorio): Estado objetivo - "Borrador", "En revisión", "Aprobado", "Arquitectura", "Listo", "Implementado", "Validado", "Obsoleto"
  • comment (opcional): Comentario de revisión o justificación, añadido una vez a cada requisito movido

Pasa requirement_id o requirement_ids, no ambos. Cada ID en una lista se mueve por separado: el resultado lista cada ID, y structuredContent contiene results (una entrada por ID, con error cuando se rechaza), moved y refused. Algunos rechazos lo convierten en una advertencia mientras los otros IDs aún se mueven; solo es un error cuando ninguno se movió.

Cuando new_status está a más de un paso de distancia, el requisito recorre la ruta permitida más corta y cada paso se registra como su propio cambio de estado: Borrador → Aprobado pasa por En revisión, y Aprobado → Validado pasa por Listo e Implementado. Un movimiento nunca pasa por Aprobado o Validado; esos solo pueden ser el destino final. Las compuertas se aplican antes de cualquier cambio, por lo que un movimiento rechazado deja el requisito donde estaba. Los resultados de múltiples pasos incluyen el path.

Transiciones de estado válidas:

  • Borrador → En revisión, Obsoleto
  • En revisión → Borrador, Aprobado, Obsoleto
  • Aprobado → Arquitectura, Listo, Obsoleto
  • Arquitectura → Listo, Aprobado
  • Listo → Implementado, Obsoleto
  • Implementado → Validado, Listo
  • Validado → Obsoleto

query_requirements

Busca y filtra requisitos por varios criterios.

Parámetros:

  • status (opcional): Filtrar por estado
  • priority (opcional): Filtrar por nivel de prioridad
  • type (opcional): Filtrar por tipo de requisito
  • search_text (opcional): Búsqueda de texto en título y estado deseado
  • work_complete (opcional): true para los requisitos cuyas tareas vinculadas están todas Completas pero que no han alcanzado Implementado: el trabajo está hecho y solo falta la decisión

trace_requirement

Rastrea un requisito a lo largo de su ciclo de vida completo de implementación.

Parámetros:

  • requirement_id (obligatorio): ID del requisito

Devuelve: Rastreo completo que incluye detalles del requisito, tareas de implementación y decisiones de arquitectura.

update_requirement

Edita el contenido de un requisito en su lugar. Consulta Edición, eliminación e historial para conocer las reglas.

Parámetros:

  • requirement_id (obligatorio): ID del 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 (al menos uno): Nuevos valores, con los mismos tipos que en create_requirement
  • reason (obligatorio en Aprobado o posterior): Por qué se realiza el cambio
  • actor (opcional): Quién realiza el cambio (predeterminado: Usuario MCP)
  • if_revision (opcional): Rechazar la edición a menos que el requisito siga en esta revisión

Ejemplo:

{
  "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
}

Gestión de tareas

create_task

Crea tareas de implementación vinculadas a requisitos.

Parámetros:

  • requirement_ids (obligatorio): Matriz de IDs de requisitos para vincular
  • title (obligatorio): Título de la tarea
  • priority (obligatorio): Nivel de prioridad - "P0", "P1", "P2", "P3"
  • effort (opcional): Estimación de esfuerzo - "XS", "S", "M", "L", "XL"
  • user_story (opcional): Descripción de historia de usuario
  • acceptance_criteria (opcional): Matriz de criterios de aceptación
  • parent_task_id (opcional): Tarea principal para subtareas
  • assignee (opcional): Persona asignada a la tarea
  • implementation_plan (opcional): Matriz de pasos de implementación
  • test_plan (opcional): Matriz de pruebas o comprobaciones a ejecutar
  • definition_of_done (opcional): Matriz de condiciones para considerar la tarea completada

Ejemplo:

{
  "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

Actualiza el progreso y la asignación de tareas.

Parámetros:

  • task_id: ID de la tarea (p. ej., "TASK-0001-00-00")
  • task_ids: En lugar de task_id, una lista de IDs de tareas para mover al mismo estado, con un resultado por ID como en update_requirement_status
  • new_status (obligatorio): Nuevo estado - "No iniciada", "En progreso", "Bloqueada", "Completa", "Abandonada"
  • comment (opcional): Comentario de actualización de estado. Al mover a Bloqueada, se conserva como motivo de bloqueo de la tarea hasta que la tarea salga de Bloqueada; mover una tarea Bloqueada a Bloqueada nuevamente sin comentario conserva el motivo
  • assignee (opcional): Nueva persona asignada
  • commit (opcional): El commit detrás de este movimiento, conservado en la tarea
  • evidence (opcional): El resultado de prueba o comprobación detrás de este movimiento, conservado en la tarea

commit y evidence permanecen en la tarea después del movimiento: un cambio de estado posterior que los omita los deja en su lugar, y pasar nuevos valores los reemplaza. Ambos aparecen en los detalles de la tarea y en la documentación de tareas exportada, por lo que el razonamiento detrás de una tarea completada sobrevive a la transferencia.

query_tasks

Busca y filtra tareas por varios criterios.

Parámetros:

  • status (opcional): Filtrar por estado
  • priority (opcional): Filtrar por nivel de prioridad
  • assignee (opcional): Filtrar por persona asignada
  • requirement_id (opcional): Filtrar por requisito vinculado
  • ready (opcional): true para tareas No iniciadas cuyas dependencias están todas Completas, primero la prioridad más alta. Una tarea espera a las tareas de las que depende o que requiere, y a las tareas que la bloquean

Los filtros se combinan.

Cuando ready no encuentra nada, la respuesta indica qué caso es en lugar de que no se encontraron tareas: no quedan tareas, cada tarea restante está esperando (con cuántas están Bloqueadas y cuántas esperan dependencias), o el único trabajo iniciable ya está En progreso.

sync_github_tasks

Sincroniza tareas desde sus issues de GitHub vinculados, con detección de conflictos. Se lista solo cuando LIFECYCLE_GITHUB=on.

Parámetros:

  • task_id (opcional): Tarea para sincronizar con su issue de GitHub vinculado; omítelo para sincronizar cada tarea vinculada a un issue

Devuelve: Estado de sincronización y cualquier actualización aplicada desde los datos del issue de GitHub.

update_task

Edita el contenido de una tarea, muévela bajo otro padre o cambia los requisitos que implementa. El ID de la tarea nunca cambia.

Parámetros:

  • task_id (obligatorio): ID de la tarea
  • title, priority, effort, user_story, acceptance_criteria, assignee, implementation_plan, test_plan, definition_of_done (opcional): Nuevos valores, con los mismos tipos que en create_task
  • parent_task_id (opcional): Nueva tarea principal; una cadena vacía la convierte en tarea de nivel superior. Una tarea no puede convertirse en su propio padre ni moverse bajo una de sus subtareas
  • requirement_ids (opcional): Reemplaza los requisitos que implementa la tarea; los requisitos que se añaden deben estar aprobados, como en create_task
  • reason, actor, if_revision (opcional): Como en update_requirement

Pasa al menos un campo para cambiar. Los cambios no se envían a un issue de GitHub vinculado.

Gestión de arquitectura

create_architecture_decision

Registra decisiones de arquitectura (ADR) con contexto completo.

Parámetros:

  • requirement_ids (obligatorio): Matriz de IDs de requisitos abordados
  • title (obligatorio): Título de la decisión
  • context (obligatorio): Contexto y antecedentes de la decisión
  • decision (obligatorio): La decisión tomada
  • consequences (opcional): Objeto de consecuencias de la decisión
  • decision_drivers (opcional): Matriz de factores que impulsan la decisión
  • considered_options (opcional): Matriz de alternativas consideradas
  • authors (opcional): Matriz de autores de la decisión
  • deciders (opcional): Matriz de personas que tomaron la decisión
  • implementation_notes (opcional): Notas para implementar la decisión
  • validation_criteria (opcional): Matriz de comprobaciones que demuestran que la decisión funciona
  • risk_assessment (opcional): Matriz de riesgos, cada uno con probabilidad, impacto y mitigación

Ejemplo:

{
  "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

Actualiza el estado de una o varias decisiones de arquitectura.

Parámetros:

  • architecture_id: ID de arquitectura (p. ej., "ADR-0001")
  • architecture_ids: En lugar de architecture_id, una lista de IDs de decisiones para mover al mismo estado, con un resultado por ID como en update_requirement_status
  • new_status (obligatorio): Nuevo estado - "Propuesta", "Aceptada", "Rechazada", "Obsoleta", "Superada", "Borrador", "En revisión", "Aprobada", "Implementada"
  • comment (opcional): Comentario de cambio de estado

Superada proviene de un enlace: create_relationship con la decisión más nueva como source_id, la más antigua como target_id y relationship_type supersedes mueve la más antigua a Superada y establece su superseded_by. Esta herramienta rechaza Superada sin ese enlace, y rechaza mover una decisión superada a otro lugar hasta que el enlace se elimine.

query_architecture_decisions

Busca y filtra decisiones de arquitectura por varios criterios.

Parámetros:

  • status (opcional): Filtrar por estado
  • type (opcional): Filtrar por tipo (ADR, TDD, INTG)
  • requirement_id (opcional): Filtrar por requisito vinculado
  • search_text (opcional): Búsqueda de texto en título y contexto

update_architecture

Edita el contenido de una decisión de arquitectura mientras está Propuesta. Las decisiones en cualquier otro estado se rechazan: registra una nueva decisión con create_architecture_decision y vincúlala a la anterior con una relación supersedes, lo que mueve la anterior a Superada.

Una decisión Aceptada puede en su lugar ser enmendada: amendment registra una corrección fechada y atribuida, que lleva su reason, contra la decisión. Nada sobre la decisión se edita: su texto, revisión y marca de tiempo se dejan exactamente como estaban, y la enmienda se almacena como un evento del ciclo de vida, por lo que get_entity_history la muestra como su propio tipo de entrada. Las enmiendas se muestran directamente debajo de la decisión que corrigen en get_details y en la documentación de arquitectura exportada, marcadas como correcciones posteriores, para que un lector no pueda asimilar el texto desactualizado sin verlas. Pasa amendment por sí solo; enmendar una decisión Propuesta se rechaza, señalando la edición que debería usarse. Parámetros:

  • architecture_id (obligatorio): ID de arquitectura
  • title, context, decision, consequences, decision_drivers, considered_options, authors, deciders, implementation_notes, validation_criteria, risk_assessment (al menos uno, al editar): Nuevos valores, con los mismos tipos que en create_architecture_decision
  • amendment (en lugar de los campos anteriores): Una corrección fechada a una decisión Aceptada
  • reason, actor, if_revision (opcional): Como en update_requirement. reason se traslada en la enmienda

Monitoreo de Proyecto

get_project_status

Obtén métricas completas de salud del proyecto y paneles de control.

Parámetros:

  • include_blocked (opcional): Incluir análisis de elementos bloqueados (predeterminado: true)

Devuelve: Panel con resumen de requisitos, estadísticas de tareas, porcentajes de finalización y elementos bloqueados: cada tarea Bloqueada con su motivo, y cada tarea o requisito que aún espera una dependencia con lo que espera. structuredContent contiene las métricas y, cuando include_blocked está activado, los mismos elementos bajo blocked.

Herramientas de Exportación de Documentación

export_project_documentation

Exporta documentación completa del proyecto en formato markdown estructurado.

Parámetros:

  • project_name (opcional): Nombre para el proyecto usado en nombres de archivo (predeterminado: "project")
  • include_requirements (opcional): Incluir documentación de requisitos (predeterminado: true)
  • include_tasks (opcional): Incluir documentación de tareas (predeterminado: true)
  • include_architecture (opcional): Incluir documentación de arquitectura (predeterminado: true)
  • output_directory (opcional): Directorio para guardar archivos exportados (predeterminado: ".")

Devuelve: Lista de archivos exportados con sus rutas.

Archivos Generados:

  • {project_name}-requirements.md - Documentación completa de requisitos agrupada por tipo
  • {project_name}-tasks.md - Documentación de tareas agrupada por estado, con requisitos vinculados, el commit y evidencia de cada tarea, y sus comentarios
  • {project_name}-architecture.md - Decisiones de arquitectura con contexto, decisiones y consecuencias

Ejemplo:

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

create_architectural_diagrams

Genera diagramas Mermaid para visualización de arquitectura y relaciones del proyecto.

Parámetros:

  • diagram_type (opcional): Tipo de diagrama - "requirements", "tasks", "architecture", "full_project", "dependencies" (predeterminado: "full_project")
  • limit (opcional): Limita cada tipo de registro. La respuesta indica qué se dibujó y qué dejó fuera el límite; sin él, nada se limita
  • requirement_ids (opcional): Matriz de IDs de requisitos específicos para incluir
  • include_relationships (opcional): Incluir flechas de relación en diagramas (predeterminado: true)
  • output_format (opcional): Formato de salida - "mermaid", "markdown_with_mermaid" (predeterminado: "mermaid")

Devuelve: Código de diagrama Mermaid o diagrama envuelto en markdown.

Tipos de Diagrama:

  • requirements: Requisitos agrupados por tipo, con bordes de padre y dependencia, en colores de estado
  • tasks: Tareas con bordes de subtarea, dependencia y bloqueo, en colores de estado
  • architecture: Decisiones, lo que reemplazan, y los requisitos que cada una aborda
  • full_project: El gráfico completo - requisitos, tareas y decisiones con cada enlace entre ellos
  • dependencies: Las tareas que esperan otras tareas, nombradas en lugar de IDs simples

Cada borde lee de origen a destino con una etiqueta, por lo que una dependencia apunta a lo que espera. Los requisitos y decisiones obsoletos se omiten, y la respuesta indica cuántos fueron. Cada tipo escribe un archivo, {diagram_type}-diagram.mmd o .md, sobrescrito en cada renderizado.

Colores de Estado:

  • Requisitos: Borrador (rojo), En Revisión (naranja), Aprobado (azul), Listo (verde), etc.
  • Tareas: No Iniciado (rojo), En Progreso (naranja), Bloqueado (rojo oscuro), Completo (verde), etc.
  • Arquitectura: Propuesto (naranja), Aceptado (verde), Rechazado (rojo), Obsoleto (gris), etc.

Ejemplo:

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

Esquema de Base de Datos

El servidor mantiene una base de datos SQLite completa con las siguientes entidades clave:

  • Requisitos: Entidad central con estados de ciclo de vida (Borrador → En Revisión → Aprobado → Arquitectura → Listo → Implementado → Validado → Obsoleto)
  • Tareas: Elementos de trabajo de implementación con estructura jerárquica (formato TASK-XXXX-YY-ZZ)
  • Arquitectura: ADRs y documentos de diseño técnico
  • Relaciones: Enlaces de muchos a muchos entre requisitos, tareas y arquitectura
  • Eventos: Registro automático de eventos de ciclo de vida y cambios de estado
  • Comentarios: Notas sobre requisitos, tareas y decisiones de arquitectura, agregadas con add_comment o el comment de un cambio de estado

IDs Cortos

En cualquier lugar donde una herramienta acepte un ID de registro, el relleno con ceros y la versión final pueden omitirse:

EscritoResuelve a
REQ-12-FUNCREQ-0012-FUNC-00
TASK-12TASK-0012-00-00
TASK-12-1TASK-0012-01-00
ADR-4ADR-0004

La forma corta de un requisito conserva su tipo, porque los números de requisito se repiten entre tipos: REQ-12 por sí solo puede significar cuatro registros diferentes. Los IDs completos almacenados siempre funcionan. Un alias que no coincide con nada se rechaza como desconocido, y uno que coincide con varios se rechaza nombrando los candidatos, por lo que una herramienta nunca actúa sobre una suposición. Los IDs almacenados nunca cambian; esto es solo una forma de entrada.

Llamadas Rechazadas

Una llamada cuyos argumentos no coinciden con el esquema de la herramienta se rechaza antes de escribir nada, nombrando el campo en falta. Cuando el parámetro rechazado tiene un vecino cercano en el mismo esquema que habría aceptado el valor, el mensaje lo nombra: pasar una lista a requirement_id responde que requirement_ids toma una matriz y acepta lo que pasaste. La sugerencia se lee del propio esquema de la herramienta, por lo que un nuevo par singular/plural se cubre el día que se declara.

Las llamadas rechazadas llegan al registro de llamadas como cualquier otra cuando LIFECYCLE_CALL_LOG está configurado, por lo que los totales de una sesión cubren las llamadas que un cliente hizo incorrectamente en lugar de solo las que llegaron a un manejador.

Formatos de ID de Entidad

  • Requisitos: REQ-XXXX-TYPE-VV (p. ej., REQ-0001-FUNC-00)
  • Tareas: TASK-XXXX-YY-ZZ (p. ej., TASK-0001-00-00)
  • Arquitectura: ADR-XXXX (p. ej., ADR-0001)

Variables de Entorno

  • LIFECYCLE_DB: Ruta al archivo de base de datos SQLite (predeterminado: "./lifecycle.db")
  • LIFECYCLE_GITHUB: Configúralo en on para crear y sincronizar un issue de GitHub para cada tarea (predeterminado: desactivado). Requiere una CLI de gh autenticada y un remoto origin de github.com en el directorio de trabajo del servidor. Cuando está desactivado, el servidor nunca ejecuta gh o git, y la herramienta sync_github_tasks no se lista.
  • LIFECYCLE_RULES: Qué tan estrictamente se tratan los movimientos de estado riesgosos - off, warn o enforce (predeterminado: warn). Cualquier otra cosa vuelve a warn.
  • LIFECYCLE_STALE_AFTER: Cuántos días puede pasar un requisito sin revisión antes de que get_project_status lo persiga (predeterminado: 14). 0 persigue cada requisito tan pronto como se escribe. Cualquier cosa que no sea un número de días vuelve al predeterminado.
  • LIFECYCLE_CALL_LOG: Ruta a un archivo donde el servidor agrega una línea JSON por llamada de herramienta: nombre de la herramienta, nombres de argumentos (no valores), duración, si falló y tamaño de respuesta. Desactivado por predeterminado. Cada llamada que recibe el servidor se registra, incluidas las que su esquema rechazó y las que nombran una herramienta que no existe: esas llevan error_kind (validation, unknown_tool) y la regla y el parámetro por los que fueron rechazadas, por lo que los totales de una sesión cubren las llamadas que un cliente hizo incorrectamente. scripts/tool_usage_report.py resume estos registros.

Escritura de Requisitos

El servidor ofrece un prompt MCP, capture_requirement, listado bajo prompts/list. Es una guía para escribir un requisito bien formado que tu propio modelo completa y luego pasa a create_requirement en una sola llamada; toma un argumento opcional about que lleva lo que la persona dijo en sus propias palabras. No se guarda nada en el servidor entre llamadas.

Los nuevos registros también indican cuándo son escasos para su tipo: un requisito sin acceptance_criteria, un requisito NFUNC sin validation_metrics, una tarea P0 o P1 sin test_plan. Estas son reglas de flujo de trabajo, por lo que advierten por predeterminado, rechazan bajo LIFECYCLE_RULES=enforce y son silenciosas bajo off.

Los detalles de un requisito muestran cuándo alguien lo verificó por última vez contra la realidad, y get_project_status lista los que vale la pena releer bajo Necesita Verificación: aquellos cuyo contenido cambió después de la última verificación, y aquellos que nadie ha verificado durante más de LIFECYCLE_STALE_AFTER días. Escribir un requisito cuenta como la primera verificación, y después comentar sobre él o mover su estado también cuenta, por lo que nada se persigue el día en que se escribió. La línea indica los dos momentos que mantiene: cuándo cambió el contenido y cuándo se verificó por última vez, y nunca afirma saber el momento en que el requisito quedó obsoleto.

Cuando cada tarea que implementa un requisito está Completa pero el requisito no ha alcanzado Implementado, el trabajo está hecho y solo falta la decisión. get_project_status nombra esos requisitos bajo Trabajo Completo, Decisión Pendiente, y query_requirements los encuentra con work_complete. Nada se mueve por sí solo: el rastreador solicita y la persona decide.

Reglas de Flujo de Trabajo

Un movimiento de estado puede ser riesgoso sin ser incorrecto. LIFECYCLE_RULES decide qué sucede entonces:

  • warn (predeterminado): el movimiento ocurre exactamente como hoy, y la respuesta indica por qué era riesgoso, en el texto y en structuredContent bajo warnings - por registro para una lista de IDs.
  • enforce: el movimiento se rechaza antes de escribir nada, nombrando lo que lo bloquea.
  • off: no se verifica nada.

Las reglas:

  • Dependencias incompletas: iniciar o completar una tarea cuyas dependencias no están todas Completas las nombra. Una dependencia abandonada se nombra por separado, con las dos formas de salir: eliminar el enlace con delete_relationship, o abandonar también la tarea que espera.
  • Subtareas abiertas: completar una tarea mientras una subtarea no está ni Completa ni Abandonada nombra las subtareas abiertas.
  • Saltos y reaperturas: completar una tarea que nunca se inició o que aún está Bloqueada, y reabrir una tarea Completa, cada uno lo indica.
  • La puerta de Implementado: un requisito que alcanza Implementado mientras las tareas que lo implementan están abiertas las nombra.
  • Movimientos de decisión: una decisión de arquitectura que se mueve fuera de su vocabulario indica dónde suele ir ese estado. Los estados de ADR y la cadena TDD son conjuntos separados.

Tres reglas están siempre activas, sea cual sea el modo, porque protegen lo que el servidor mantiene por sí mismo: un requisito no puede ser Validado mientras una tarea vinculada esté abierta, Superseded necesita un enlace supersedes, y el estado de un requisito aún sigue su mapa de transición.

Solución de Problemas

Problemas de Conexión

"MCP error -32000: Connection closed"

El servidor salió o escribió algo distinto a mensajes de protocolo en stdout. Para verificar una instalación:

python3 scripts/mcp_handshake_smoke.py lifecycle-mcp

Esto inicia el servidor dos veces contra una base de datos temporal e informa si el handshake de MCP tiene éxito con stdout limpio. Si falla:

  1. Reinstala para que se use el SDK de MCP fijado (mcp[cli]>=1.10,<2):

    uv tool install --force .

  2. Vuelve a agregar el servidor MCP:

    claude mcp add lifecycle lifecycle-mcp

  3. Verifica que el servidor se inicie sin errores:

    lifecycle-mcp

Servidor No Encontrado

Si el comando lifecycle-mcp no se encuentra después de la instalación:

  1. Verifica que la instalación se completó correctamente
  2. Verifica que el punto de entrada esté registrado en pyproject.toml
  3. Intenta reinstalar con pip install -e .

Problemas de Base de Datos

Errores de Bloqueo de Base de Datos

Si ves errores de bloqueo de base de datos, asegúrate de que solo una instancia del servidor esté ejecutándose y que el archivo de base de datos tenga permisos adecuados.

Inicialización del Esquema

El esquema de la base de datos se crea automáticamente en la primera ejecución. Si necesitas restablecer la base de datos, simplemente elimina el archivo SQLite (predeterminado: lifecycle.db).

Desarrollo

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

Construcción de la Extensión de Escritorio (.dxt)

Para crear un paquete de Extensión de Escritorio para instalación con un clic:

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

Esto crea lifecycle-mcp-1.0.0.dxt que los usuarios pueden hacer doble clic para instalar en Claude Desktop.