iflow-mcp_heffrey78-lifecycle-mcp 1.0.0
MCP server for software lifecycle management
License: MIT
Requires Python: >=3.10

# 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

```bash
# 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):
```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or with homebrew
brew install uv
```

### Clone the Repository
```bash
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](USAGE_EXAMPLES.md).

### Option 1: Global Installation (Recommended for Multiple Projects)

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

```bash
# 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:

```bash
# 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:

```bash
# 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`

```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)
```bash
# 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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:
   ```bash
   pip install -e .
   ```

2. Re-add the MCP server:
   ```bash
   claude mcp add lifecycle lifecycle-mcp
   ```

3. Check that the server starts without errors:
   ```bash
   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)
```bash
# 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)
```bash
# 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:

```bash
# 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.