lifecycle-mcp

Lifecycle MCP Server

A Model Context Protocol (MCP) server for comprehensive software lifecycle management. This server provides structured tracking of requirements, tasks, and architecture decisions through a SQLite database with full traceability and automated state management.

Features

• Requirements Management: Create and manage software requirements with validation and lifecycle tracking
• Task Management: Track implementation tasks with hierarchical structure and effort estimation
• Architecture Decisions: Record ADRs (Architecture Decision Records) with full context
• Project Dashboards: Real-time project health metrics and status reporting
• Requirement Tracing: Complete traceability from requirements through implementation
• State Validation: Automatic validation of lifecycle state transitions
• Relationship Tracking: Many-to-many relationships between requirements, tasks, and architecture

Quick Start

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

# 2. Install globally (easiest for using across projects)
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!

Installation Options

Prerequisites (Optional)

If you want to use uv (faster Python package manager):

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

# Or with homebrew
brew install uv

Clone the Repository

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

Usage with Claude Code

For detailed examples and scenarios, see USAGE_EXAMPLES.md.

Option 1: Global Installation (Recommended for Multiple Projects)

Install the server globally so it can be used from any project:

# From the lifecycle-mcp directory
pip install -e .

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

Note: Each project gets its own database file in its directory.

Option 2: Run from Source with uv

If you prefer not to install globally:

# 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

Option 3: Direct Python Execution

For maximum compatibility:

# 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

Manual Configuration

You can also manually edit your Claude Desktop configuration file:

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

Best Practices

Database Location

• Each project should have its own lifecycle.db file
• Use LIFECYCLE_DB=./lifecycle.db to create the database in the current project
• Or use an absolute path for a shared database: LIFECYCLE_DB=/path/to/shared/lifecycle.db

Virtual Environment (Recommended)

# 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

MCP Tools Reference

The server exposes 22 MCP tools across 6 handler modules for comprehensive lifecycle management:

Tool List

• create_requirement - Create new requirements from interview data
• update_requirement_status - Move requirements through lifecycle states
• query_requirements - Search and filter requirements
• get_requirement_details - Get full requirement with relationships
• trace_requirement - Trace requirement through implementation
• create_task - Create implementation tasks from requirements
• update_task_status - Update task progress
• query_tasks - Search and filter tasks
• get_task_details - Get full task details with dependencies
• sync_task_from_github - Sync individual task from GitHub issue changes
• bulk_sync_github_tasks - Sync all tasks with their GitHub issues
• create_architecture_decision - Record architecture decisions (ADRs)
• update_architecture_status - Update architecture decision status
• query_architecture_decisions - Search and filter architecture decisions
• get_architecture_details - Get full architecture decision details
• add_architecture_review - Add review comments to architecture decisions
• get_project_status - Get project health metrics and dashboards
• start_requirement_interview - Start interactive requirement gathering
• continue_requirement_interview - Continue requirement interview sessions
• start_architectural_conversation - Start interactive architecture discussions
• continue_architectural_conversation - Continue architecture conversations
• export_project_documentation - Export comprehensive markdown documentation
• create_architectural_diagrams - Generate Mermaid diagrams for project visualization

Requirement Management

create_requirement

Create new requirements from interview data or analysis.

Parameters:

• type (required): Requirement type - "FUNC", "NFUNC", "TECH", "BUS", "INTF"
• title (required): Descriptive title
• priority (required): Priority level - "P0", "P1", "P2", "P3"
• current_state (required): Current system state
• desired_state (required): Target system state
• functional_requirements (optional): Array of functional requirements
• acceptance_criteria (optional): Array of acceptance criteria
• business_value (optional): Business justification
• risk_level (optional): Risk assessment - "High", "Medium", "Low"
• author (optional): Requirement author

Example:

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

Move requirements through their lifecycle with validation.

Parameters:

• requirement_id (required): Requirement ID (e.g., "REQ-0001-FUNC-00")
• new_status (required): Target status - "Draft", "Under Review", "Approved", "Architecture", "Ready", "Implemented", "Validated", "Deprecated"
• comment (optional): Review comment or justification

Valid State Transitions:

• Draft → Under Review, Deprecated
• Under Review → Draft, Approved, Deprecated
• Approved → Architecture, Ready, Deprecated
• Architecture → Ready, Approved
• Ready → Implemented, Deprecated
• Implemented → Validated, Ready
• Validated → Deprecated

query_requirements

Search and filter requirements by various criteria.

Parameters:

• status (optional): Filter by status
• priority (optional): Filter by priority level
• type (optional): Filter by requirement type
• search_text (optional): Text search in title and desired state

get_requirement_details

Get comprehensive requirement information including all relationships.

Parameters:

• requirement_id (required): Requirement ID

Returns: Detailed report with basic info, problem definition, functional requirements, acceptance criteria, and linked tasks.

trace_requirement

Trace a requirement through its complete implementation lifecycle.

Parameters:

• requirement_id (required): Requirement ID

Returns: Complete trace including requirement details, implementation tasks, and architecture decisions.

Task Management

create_task

Create implementation tasks linked to requirements.

Parameters:

• requirement_ids (required): Array of requirement IDs to link
• title (required): Task title
• priority (required): Priority level - "P0", "P1", "P2", "P3"
• effort (optional): Effort estimation - "XS", "S", "M", "L", "XL"
• user_story (optional): User story description
• acceptance_criteria (optional): Array of acceptance criteria
• parent_task_id (optional): Parent task for subtasks
• assignee (optional): Task assignee

Example:

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

Update task progress and assignment.

Parameters:

• task_id (required): Task ID (e.g., "TASK-0001-00-00")
• new_status (required): New status - "Not Started", "In Progress", "Blocked", "Complete", "Abandoned"
• comment (optional): Status update comment
• assignee (optional): New assignee

query_tasks

Search and filter tasks by various criteria.

Parameters:

• status (optional): Filter by status
• priority (optional): Filter by priority level
• assignee (optional): Filter by assignee
• requirement_id (optional): Filter by linked requirement

get_task_details

Get comprehensive task information including dependencies and relationships.

Parameters:

• task_id (required): Task ID

Returns: Detailed report with basic info, description, acceptance criteria, and linked requirements.

sync_task_from_github

Sync individual task from GitHub issue changes with conflict detection.

Parameters:

• task_id (required): Task ID to sync with its linked GitHub issue

Returns: Sync status and any updates applied from GitHub issue data.

bulk_sync_github_tasks

Sync all tasks with their GitHub issues in batch operation.

Parameters: None

Returns: Summary of sync operations performed across all tasks with GitHub issue links.

Architecture Management

create_architecture_decision

Record architecture decisions (ADRs) with full context.

Parameters:

• requirement_ids (required): Array of requirement IDs addressed
• title (required): Decision title
• context (required): Decision context and background
• decision (required): The decision made
• consequences (optional): Decision consequences object
• decision_drivers (optional): Array of factors driving the decision
• considered_options (optional): Array of alternatives considered
• authors (optional): Array of decision authors

Example:

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

Update the status of an architecture decision with validation.

Parameters:

• architecture_id (required): Architecture ID (e.g., "ADR-0001")
• new_status (required): New status - "Proposed", "Accepted", "Rejected", "Deprecated", "Superseded", "Draft", "Under Review", "Approved", "Implemented"
• comment (optional): Status change comment

query_architecture_decisions

Search and filter architecture decisions by various criteria.

Parameters:

• status (optional): Filter by status
• type (optional): Filter by type (ADR, TDD, INTG)
• requirement_id (optional): Filter by linked requirement
• search_text (optional): Text search in title and context

get_architecture_details

Get comprehensive architecture decision information including all relationships and reviews.

Parameters:

• architecture_id (required): Architecture ID

Returns: Detailed report with basic info, context, decision details, drivers, options, consequences, linked requirements, and review history.

add_architecture_review

Add review comments to architecture decisions.

Parameters:

• architecture_id (required): Architecture ID
• comment (required): Review comment
• reviewer (optional): Reviewer name (default: "MCP User")

Project Monitoring

get_project_status

Get comprehensive project health metrics and dashboards.

Parameters:

• include_blocked (optional): Include blocked items analysis (default: true)

Returns: Dashboard with requirement overview, task statistics, completion percentages, and blocked items analysis.

Interactive Interview Tools

start_requirement_interview

Start an interactive requirement gathering interview session.

Parameters:

• project_context (optional): Description of the project or system
• stakeholder_role (optional): Role of the person being interviewed

Returns: Session ID and initial questions to guide requirement gathering.

Example:

{
  "project_context": "E-commerce platform modernization",
  "stakeholder_role": "Product Manager"
}

continue_requirement_interview

Continue an active interview session by providing answers to questions.

Parameters:

• session_id (required): Interview session ID from start_requirement_interview
• answers (required): Object containing answers to the current questions

Returns: Next set of questions or completion summary with created requirement.

Example:

{
  "session_id": "a1b2c3d4",
  "answers": {
    "current_problem": "Users struggle with complex checkout process",
    "desired_outcome": "Streamlined one-click checkout experience",
    "success_criteria": "Checkout completion rate increases by 25%"
  }
}

Interview Flow:

1. Problem Identification: Understanding the current challenge
2. Solution Definition: Defining the desired outcome and constraints
3. Details Gathering: Collecting priority, type, and technical details
4. Validation: Establishing acceptance criteria and success metrics
5. Completion: Automatic requirement creation with interview summary

Documentation Export Tools

export_project_documentation

Export comprehensive project documentation in structured markdown format.

Parameters:

• project_name (optional): Name for the project used in filenames (default: "project")
• include_requirements (optional): Include requirements documentation (default: true)
• include_tasks (optional): Include tasks documentation (default: true)
• include_architecture (optional): Include architecture documentation (default: true)
• output_directory (optional): Directory to save exported files (default: ".")

Returns: List of exported files with their paths.

Generated Files:

• {project_name}-requirements.md - Complete requirements documentation grouped by type
• {project_name}-tasks.md - Task documentation grouped by status with linked requirements
• {project_name}-architecture.md - Architecture decisions with context, decisions, and consequences

Example:

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

create_architectural_diagrams

Generate Mermaid diagrams for project architecture and relationships visualization.

Parameters:

• diagram_type (optional): Type of diagram - "requirements", "tasks", "architecture", "full_project", "directory_structure", "dependencies" (default: "full_project")
• requirement_ids (optional): Array of specific requirement IDs to include
• include_relationships (optional): Include relationship arrows in diagrams (default: true)
• output_format (optional): Output format - "mermaid", "markdown_with_mermaid" (default: "mermaid")
• interactive (optional): Start interactive conversation for complex diagrams (default: false)

Returns: Mermaid diagram code or markdown-wrapped diagram.

Diagram Types:

• requirements: Flowchart showing requirement hierarchy by type with status colors
• tasks: Task hierarchy with parent-child relationships and status indicators
• architecture: Architecture decisions with status-based styling
• full_project: High-level overview showing relationships between requirements, tasks, and architecture
• directory_structure: Project directory structure visualization
• dependencies: Task dependency graph showing blocking relationships

Status Colors:

• Requirements: Draft (red), Under Review (orange), Approved (blue), Ready (green), etc.
• Tasks: Not Started (red), In Progress (orange), Blocked (dark red), Complete (green), etc.
• Architecture: Proposed (orange), Accepted (green), Rejected (red), Deprecated (gray), etc.

Example:

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

Interactive Architectural Conversation Tools

start_architectural_conversation

Start an interactive conversation for complex architectural diagram generation.

Parameters:

• project_context (optional): Description of the project or system
• diagram_purpose (optional): Purpose and goals for the diagram
• complexity_level (optional): Conversation complexity - "simple", "medium", "complex" (default: "medium")

Returns: Session ID and contextual questions based on complexity level.

Complexity Levels:

• Simple: Basic component and relationship questions
• Medium: Architectural challenges, stakeholders, and detail level questions
• Complex: Deep architectural patterns, compliance, security, and performance considerations

continue_architectural_conversation

Continue an active architectural conversation session with responses.

Parameters:

• session_id (required): Conversation session ID from start_architectural_conversation
• responses (required): Object containing responses to current questions

Returns: Next questions or completion with generated diagram.

Conversation Flow:

1. Context Gathering: Understanding architectural needs and stakeholders
2. Diagram Specification: Determining optimal diagram type and focus
3. Detail Refinement: Visual preferences and emphasis areas
4. Completion: Automatic diagram generation with conversation summary

Example:

{
  "session_id": "a1b2c3d4",
  "responses": {
    "main_challenge": "Visualizing microservice dependencies for new team members",
    "stakeholders": "Development team and system architects",
    "detail_level": "High-level overview with key integration points"
  }
}

Database Schema

The server maintains a comprehensive SQLite database with the following key entities:

• Requirements: Central entity with lifecycle states (Draft → Under Review → Approved → Architecture → Ready → Implemented → Validated → Deprecated)
• Tasks: Implementation work items with hierarchical structure (TASK-XXXX-YY-ZZ format)
• Architecture: ADRs and technical design documents
• Relationships: Many-to-many links between requirements, tasks, and architecture
• Events: Automatic logging of lifecycle events and status changes
• Reviews: Comments and feedback on requirements and tasks

Entity ID Formats

• Requirements: REQ-XXXX-TYPE-VV (e.g., REQ-0001-FUNC-00)
• Tasks: TASK-XXXX-YY-ZZ (e.g., TASK-0001-00-00)
• Architecture: ADR-XXXX (e.g., ADR-0001)

Environment Variables

• LIFECYCLE_DB: Path to SQLite database file (default: "./lifecycle.db")

Troubleshooting

Connection Issues

"MCP error -32000: Connection closed"

This error typically occurs when there are async/await mismatches in the server implementation. If you encounter this:

1. Ensure the package is properly installed:

   pip install -e .
   

2. Re-add the MCP server:

   claude mcp add lifecycle lifecycle-mcp
   

3. Check that the server starts without errors:

   lifecycle-mcp
   

Server Not Found

If the lifecycle-mcp command is not found after installation:

1. Verify installation completed successfully
2. Check that the entry point is registered in pyproject.toml
3. Try reinstalling with pip install -e .

Database Issues

Database Lock Errors

If you see database lock errors, ensure only one instance of the server is running and that the database file has proper permissions.

Schema Initialization

The database schema is automatically created on first run. If you need to reset the database, simply delete the SQLite file (default: lifecycle.db).

Development

Using uv (Recommended)

# 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

Using pip (Traditional)

# Install in development mode
pip install -e .

# Run the server
lifecycle-mcp

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

Building Desktop Extension (.dxt)

To create a Desktop Extension package for one-click installation:

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

This creates lifecycle-mcp-1.0.0.dxt which users can double-click to install in Claude Desktop.