# 1. Clone the repository
git clone https://github.com/yourusername/bmad-mcp-server.git
cd bmad-mcp-server

# 2. Install dependencies
pip install -r requirements.txt

# 3. Set up environment variables
cp .env.example .env
# Edit .env with your API keys

{
  "mcpServers": {
    "bmad": {
      "command": "python",
      "args": ["-m", "src.bmad_mcp.server"],
      "cwd": "/path/to/bmad-mcp-server",
      "env": {
        "PYTHONPATH": "/path/to/bmad-mcp-server",
        "OPENROUTER_API_KEY": "your_openrouter_api_key",
        "NOTION_TOKEN": "your_notion_token"
      }
    }
  }
}

{
  "mcp.servers": {
    "bmad": {
      "command": "python",
      "args": ["-m", "src.bmad_mcp.server"],
      "cwd": "/path/to/bmad-mcp-server",
      "env": {
        "PYTHONPATH": "/path/to/bmad-mcp-server",
        "OPENROUTER_API_KEY": "your_openrouter_api_key"
      }
    }
  }
}

# List available agents
bmad_list_agents()

# Activate developer agent
bmad_activate_agent(agent="dev")

# Create a new task
bmad_create_task(
    task_id="feature-implementation",
    name="Implement user authentication",
    allocated_hours=8.0,
    agent="dev"
)

# Update progress
bmad_update_task_progress(
    task_id="feature-implementation", 
    hours_completed=2.5
)

# Get daily overview
bmad_get_today_tasks()

# Start live monitoring
bmad_start_realtime_mode()

# Begin work session
bmad_start_work_session(task_id="feature-implementation")

# Work on task...

# End session with automatic progress logging
bmad_end_work_session(
    task_id="feature-implementation",
    hours_worked=2.0
)

# Get comprehensive status
bmad_get_realtime_status()

# Start time tracking for a task
bmad_start_timer(
    task_id="feature-implementation",
    agent="dev",
    session_type="development",
    description="Implementing user authentication system"
)

# Stop timer with AI cost calculation
bmad_stop_timer(
    task_id="feature-implementation",
    ai_model_used="claude-sonnet-4",
    tokens_input=1500,
    tokens_output=800,
    mark_completed=False
)

# Get task time summary
bmad_get_task_time_summary(task_id="feature-implementation")

# Generate project billing report
bmad_get_project_billing(
    project_id="my-project-id",
    start_date="2025-01-01",
    end_date="2025-01-31",
    export_format="invoice"  # json, csv, or invoice
)

# Get daily tracking report
bmad_get_daily_time_report(date="2025-01-20")

# Auto-end stale sessions (running >8 hours)
bmad_auto_end_stale_sessions(max_hours=8)

# Detect BMAD project
bmad_detect_project(path="./my-project")

# Register in global registry
bmad_register_project(
    project_path="./my-project",
    project_name="My Awesome Project"
)

# Get project overview
bmad_get_project_status()

# List available templates
bmad_list_project_templates()

# Get template details
bmad_get_project_template_info(template_name="web-app")

# Create new project with template
bmad_create_project(
    project_path="./my-web-app",
    template="web-app",
    name="My Web Application",
    description="Modern React-based web application"
)

# Migrate existing project
bmad_migrate_project_to_standard(
    project_path="./legacy-project",
    backup=True
)

# Simulate full work day
bmad_simulate_work_day(speed_factor=10.0)

# Test specific agent workflow
bmad_simulate_agent_workday(agent="qa", hours=6.0)

# Simulate crisis scenarios
bmad_simulate_crisis_scenario(crisis_type="blocked_task")

# Start comprehensive work session
bmad_start_timer(
    task_id="user-auth-system",
    agent="dev",
    session_type="development",
    description="Implementing OAuth2 integration"
)

# Work on task with AI assistance
# ... development work with AI model usage ...

# Stop timer with detailed AI cost tracking
bmad_stop_timer(
    task_id="user-auth-system",
    ai_model_used="claude-sonnet-4",
    tokens_input=2500,
    tokens_output=1200,
    mark_completed=True
)

# Generate comprehensive project billing
billing_report = bmad_get_project_billing(
    project_id="client-project-2025",
    start_date="2025-01-01",
    end_date="2025-01-31",
    export_format="invoice"
)

# Monitor daily productivity
daily_report = bmad_get_daily_time_report("2025-01-20")
print(f"Today: {daily_report['total_hours']:.2f}h, ${daily_report['total_cost_usd']:.2f}")

# Automatic session management
bmad_auto_end_stale_sessions(max_hours=6)  # End sessions > 6 hours

bmad-mcp-server/
├── src/
│   └── bmad_mcp/
│       ├── core/                    # Core functionality
│       │   ├── task_tracker.py      # Advanced task management
│       │   ├── time_cost_tracker.py # Time & cost tracking ⭐ NEW!
│       │   ├── console_formatter.py # Live output formatting  
│       │   ├── realtime_updater.py  # Real-time monitoring
│       │   ├── time_monitor.py      # Scheduled monitoring
│       │   ├── simulator.py         # Demo & testing
│       │   ├── notion_sync.py       # Notion integration
│       │   └── global_registry.py   # Cross-IDE projects
│       ├── agents/                  # Agent definitions
│       │   ├── analyst.py           # Business analysis
│       │   ├── architect.py         # System design
│       │   ├── developer.py         # Code implementation
│       │   ├── project_manager.py   # Project coordination
│       │   ├── qa.py               # Quality assurance
│       │   └── coder.py           # Advanced semantic code analysis and editing
│       ├── workflows/              # BMAD-METHOD workflow system
│       │   ├── workflow_engine.py  # Central workflow orchestration
│       │   ├── orchestrator_agent.py # Project/Story lifecycle management
│       │   ├── quality_gates.py    # Quality assurance (@qa commands)
│       │   └── workflow_states.py  # State machine definitions
│       ├── tools/                   # MCP tool implementations
│       ├── routing/                 # OpenRouter integration
│       └── server.py               # MCP server
├── config/                         # Configuration templates
├── docs/                          # Documentation
├── examples/                      # Usage examples
└── tests/                        # Test suite

# Required
OPENROUTER_API_KEY=your_openrouter_api_key_here

# Optional  
NOTION_TOKEN=your_notion_integration_token
BMAD_MAX_DAILY_HOURS=10
BMAD_DEFAULT_AGENT=dev
BMAD_LOG_LEVEL=INFO

# config/bmad-global-config.yaml
agents:
  dev:
    model: "anthropic/claude-3.5-sonnet"
    temperature: 0.1
    max_tokens: 4000
  architect:
    model: "anthropic/claude-3-opus"
    temperature: 0.3
    max_tokens: 8000

# Build and run with Docker Compose
docker-compose up -d

# Environment variables via .env file
cp .env.example .env
# Edit .env file with your API keys
docker-compose up -d

# Run test suite
python -m pytest tests/

# Run specific test category
python -m pytest tests/test_task_management.py

# Run with coverage
python -m pytest --cov=src/bmad_mcp tests/