# Installation Guide: Vibe Kanban & dev-manager-mcp

This guide will help you install and configure Vibe Kanban and dev-manager-mcp for managing your development workflow with isolated test environments.

## Prerequisites

- Node.js >= 18 (or Bun)
- Docker installed and running
- PostgreSQL client (psql) installed
- Main database running on localhost:5432

## Part 1: Install dev-manager-mcp

dev-manager-mcp is a daemon that manages multiple dev servers in parallel, allocating unique ports to avoid collisions.

### Installation

**Option 1: Use via npx (Recommended - No Installation Needed)**

No installation required! Just use `npx`:

```bash
# Start the daemon
npx -y dev-manager-mcp daemon
```

**Option 2: Install Globally**

```bash
npm install -g dev-manager-mcp
# or
bun install -g dev-manager-mcp
```

### Start the Daemon

Open a terminal and keep it running:

```bash
npx -y dev-manager-mcp daemon
```

You should see output indicating the daemon is running. Keep this terminal open.

### Verify Installation

In another terminal, test the MCP connection:

```bash
# Check if daemon is accessible
npx dev-manager-mcp status
```

## Part 2: Install Vibe Kanban

Vibe Kanban is a task management system that integrates with coding agents and can automatically start dev environments.

### Installation

**Option 1: Use via npx (Recommended - No Installation Needed)**

```bash
# Just run it - no installation needed
npx vibe-kanban
```

**Option 2: Install Globally**

```bash
npm install -g vibe-kanban
# or
bun install -g vibe-kanban
```

### First Run

1. **Start Vibe Kanban:**

```bash
npx vibe-kanban
```

2. **Authenticate with your coding agent:**
   - Vibe Kanban will prompt you to authenticate
   - Follow the instructions for your agent (Claude, Codex, etc.)

3. **Access the UI:**
   - Vibe Kanban will start a web server
   - Open the URL shown in the terminal (usually http://localhost:3000)

### Configure MCP Integration

1. **Open Vibe Kanban Settings:**
   - In the Vibe Kanban UI, go to Settings
   - Find "MCP Servers" or "Agent Configuration"

2. **Add dev-manager-mcp:**
   ```json
   {
     "mcpServers": {
       "dev-manager": {
         "command": "npx",
         "args": ["dev-manager-mcp", "stdio"]
       }
     }
   }
   ```

3. **Configure QA Automation:**
   - In Settings, find "QA" or "Testing" section
   - Enable "Auto-start dev environments"
   - Set script path: `scripts/start-task-docker.sh`
   - Set health check URL: `http://localhost:{port}/health`

## Part 3: Configure for Your Project

### Create Vibe Kanban Configuration

**Recommended: At Projects level** (to manage all projects):

Create a `.vibe-kanban` directory in your Projects folder:

```bash
cd /Users/oda/Desktop/Projects
mkdir -p .vibe-kanban
```

Create `/Users/oda/Desktop/Projects/.vibe-kanban/config.json`:

```json
{
  "projectRoot": "/Users/oda/Desktop/Projects",
  "mcpServers": {
    "dev-manager": {
      "command": "npx",
      "args": ["dev-manager-mcp", "stdio"]
    }
  },
  "qa": {
    "enabled": true,
    "autoStartDevEnv": true,
    "devEnvScript": "managing-apps/scripts/start-task-docker.sh",
    "healthCheckUrl": "http://localhost:{port}/health",
    "dashboardUrl": "http://localhost:{port}"
  },
  "tasks": {
    "statuses": {
      "ready-for-qa": {
        "autoStartDevEnv": true
      }
    }
  }
}
```

**Note**: The `devEnvScript` path is relative to the Projects folder. For managing-apps, it's `managing-apps/scripts/start-task-docker.sh`. For other projects, configure project-specific scripts in Vibe Kanban's project settings.

### Update Your MCP Configuration

If you're using Cursor or another editor with MCP support, add to your MCP config (usually `~/.cursor/mcp.json` or similar):

```json
{
  "mcpServers": {
    "dev-manager": {
      "command": "npx",
      "args": ["dev-manager-mcp", "stdio"]
    }
  }
}
```

## Part 4: Usage Workflow

### For Development (Agent)

1. **Make code changes**
2. **Start test environment:**
   ```bash
   cd /Users/oda/Desktop/Projects/managing-apps
   bash scripts/start-dev-env.sh DEV-A3X9
   ```
3. **Test your changes** at the provided URLs
4. **Stop when done:**
   ```bash
   bash scripts/stop-task-docker.sh DEV-A3X9
   ```

### For QA (Vibe Kanban)

1. **Move task to "Ready for QA" status**
2. **Vibe Kanban automatically:**
   - Starts a Docker environment
   - Copies the database
   - Provides test URLs
3. **Test the task**
4. **Move to "Done" or "Needs Changes"**
5. **Vibe Kanban automatically stops the environment**

### Manual Management

**Start an environment:**
```bash
cd /Users/oda/Desktop/Projects/managing-apps
bash scripts/start-task-docker.sh TASK-123 0
```

**Check status:**
```bash
npx dev-manager-mcp status
```

**View logs:**
```bash
docker logs managing-api-TASK-123
```

**Stop an environment:**
```bash
bash scripts/stop-task-docker.sh TASK-123
```

## Troubleshooting

### dev-manager-mcp Issues

**Daemon not starting:**
- Check Node.js version: `node --version` (needs >= 18)
- Try: `npx -y dev-manager-mcp daemon --verbose`

**Cannot connect to daemon:**
- Make sure daemon is running in another terminal
- Check if port is already in use
- Restart the daemon

### Vibe Kanban Issues

**Cannot start:**
- Check Node.js version: `node --version` (needs >= 18)
- Try: `npx vibe-kanban --verbose`

**MCP not working:**
- Verify dev-manager-mcp daemon is running
- Check MCP configuration in Vibe Kanban settings
- Restart Vibe Kanban

**Auto-start not working:**
- Check script path in configuration
- Verify script is executable: `chmod +x scripts/start-task-docker.sh`
- Check Vibe Kanban logs

### Docker Issues

**Port conflicts:**
- Use different port offset: `bash scripts/start-task-docker.sh TASK-123 10`
- Check what's using ports: `lsof -i :5000`

**Database copy fails:**
- Verify main database is running: `docker ps | grep postgres`
- Check PostgreSQL client: `which psql`
- Verify connection: `PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d managing -c '\q'`

## Next Steps

1. ✅ Install dev-manager-mcp (via npx)
2. ✅ Install Vibe Kanban (via npx)
3. ✅ Start dev-manager-mcp daemon
4. ✅ Start Vibe Kanban
5. ✅ Configure MCP integration
6. ✅ Test with a sample task

## Resources

- [Vibe Kanban GitHub](https://github.com/BloopAI/vibe-kanban)
- [Vibe Kanban Documentation](https://www.vibekanban.com/vibe-guide)
- [dev-manager-mcp GitHub](https://github.com/BloopAI/dev-manager-mcp)
- [MCP Documentation](https://modelcontextprotocol.io/)

## Support

- Vibe Kanban: [GitHub Discussions](https://github.com/BloopAI/vibe-kanban/discussions)
- dev-manager-mcp: [GitHub Issues](https://github.com/BloopAI/dev-manager-mcp/issues)