# Claude Code Development Environment Setup

A comprehensive development environment setup for Claude Code with MCP servers, dev containers, and long-running job capabilities.

## 🚀 Quick Start

1. **Clone this repository:**
   ```bash
   git clone https://github.com/your-username/claude-dev-setup.git
   cd claude-dev-setup
   ```

2. **Set up environment variables:**
   ```bash
   cp .env.example .env
   # Edit .env with your API tokens
   ```

3. **Start the dev container:**
   ```bash
   # Using VS Code Dev Containers extension
   code .
   # Or using Docker Compose directly
   docker-compose up -d
   ```

4. **Initialize MCP servers:**
   ```bash
   ./.devcontainer/init-mcp.sh
   ```

5. **Start a long-running job:**
   ```bash
   ./scripts/ten-minute-job.sh
   ```

## 📋 Table of Contents

- [Features](#features)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
- [Documentation](#documentation)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)

## ✨ Features

### Development Environment
- **VS Code Dev Container** with pre-configured extensions
- **Docker-based** isolated development environment
- **Zsh with Oh-My-Zsh** for enhanced terminal experience
- **Git Delta** for better diff visualization

### MCP (Model Context Protocol) Servers
- **Filesystem Server**: File operations and project management
- **Monday.com Integration**: Project management and task tracking
- **Figma Integration**: Design system access and component management
- **Playwright Integration**: Browser automation and testing

### Long-Running Jobs
- **Auto-continuation**: Jobs that persist across sessions
- **Monitoring**: Real-time progress tracking
- **Logging**: Comprehensive job logging and analysis
- **Templates**: Pre-built job templates for common tasks

### Security & Networking
- **Firewall Configuration**: Automated network security setup
- **Permission Management**: Controlled access to system resources
- **Token Management**: Secure handling of API credentials

## 🔧 Prerequisites

- **Docker Desktop** or **Docker Engine** with Docker Compose
- **VS Code** with Dev Containers extension (recommended)
- **Git** for version control
- **Node.js 20+** (included in container)

### Required API Tokens

| Service | Required | Purpose | How to Get |
|---------|----------|---------|------------|
| GitHub | ✅ Yes | Repository operations | [GitHub Settings → Developer settings → Personal access tokens](https://github.com/settings/tokens) |
| Monday.com | ⚪ Optional | Project management | [Monday.com → Admin → API](https://auth.monday.com/oauth2/authorize) |
| Figma | ⚪ Optional | Design system access | [Figma → Settings → Account → Personal access tokens](https://www.figma.com/developers/api#access-tokens) |

## 📦 Installation

### Method 1: VS Code Dev Container (Recommended)

1. **Clone and open in VS Code:**
   ```bash
   git clone https://github.com/your-username/claude-dev-setup.git
   cd claude-dev-setup
   code .
   ```

2. **When prompted, click "Reopen in Container"**
   - VS Code will automatically build and start the dev container
   - All dependencies will be installed automatically

3. **Set up environment variables:**
   ```bash
   cp .env.example .env
   # Edit .env with your API tokens
   ```

### Method 2: Docker Compose

1. **Clone the repository:**
   ```bash
   git clone https://github.com/your-username/claude-dev-setup.git
   cd claude-dev-setup
   ```

2. **Configure environment:**
   ```bash
   cp .env.example .env
   # Edit .env with your API tokens
   ```

3. **Start the container:**
   ```bash
   docker-compose up -d
   ```

4. **Access the container:**
   ```bash
   docker-compose exec claude-dev zsh
   ```

### Method 3: Local Installation

If you prefer to run without containers:

1. **Install Node.js dependencies:**
   ```bash
   npm install -g \
     @anthropic-ai/claude-code \
     @modelcontextprotocol/server-filesystem \
     @mondaydotcomorg/monday-api-mcp \
     @playwright/mcp \
     figma-developer-mcp
   ```

2. **Set up environment:**
   ```bash
   cp .env.example .env
   source .env
   ```

3. **Run initialization scripts:**
   ```bash
   chmod +x .devcontainer/*.sh scripts/*.sh
   ./.devcontainer/init-mcp.sh
   ```

## ⚙️ Configuration

### Environment Variables

Edit `.env` file with your configuration:

```bash
# Required: GitHub Personal Access Token
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here

# Optional: Monday.com API token
MONDAY_API_TOKEN=your_monday_token_here

# Optional: Figma API token
FIGMA_TOKEN=your_figma_token_here

# Optional: Timezone (defaults to UTC)
TZ=America/New_York

# Optional: Node.js memory limit
NODE_OPTIONS=--max-old-space-size=8192
```

### MCP Server Configuration

MCP servers are automatically configured during container startup. To manually configure:

```bash
# Add MCP servers to Claude
claude mcp add filesystem "npx @modelcontextprotocol/server-filesystem /workspace"
claude mcp add monday "npx @mondaydotcomorg/monday-api-mcp --token $MONDAY_API_TOKEN"
claude mcp add playwright "npx @playwright/mcp"
claude mcp add figma "npx figma-developer-mcp --figma-api-key=$FIGMA_TOKEN --stdio"

# Verify configuration
claude mcp list
```

## 🎯 Usage

### Quick Commands

```bash
# Start MCP servers
./.devcontainer/start-mcps.sh

# Run a 10-minute demo job
./scripts/ten-minute-job.sh

# Start custom long-running job
./scripts/run-long-claude-job.sh "Your task description"

# Monitor job progress
./scripts/monitor-job.sh /workspace/claude-job-*.log

# Check system status
docker-compose ps
ps aux | grep claude
```

### Development Workflow

1. **Start development environment:**
   ```bash
   # Open in VS Code
   code .
   # Or start container manually
   docker-compose up -d
   ```

2. **Initialize your project:**
   ```bash
   # Create new project
   mkdir my-project && cd my-project
   npm init -y
   
   # Start Claude Code
   claude-code --dangerously-skip-permissions
   ```

3. **Run long-running analysis:**
   ```bash
   ./scripts/ten-minute-job.sh
   # Monitor in another terminal
   tail -f /workspace/claude-job-*.log
   ```

### Job Templates

#### Code Analysis
```bash
./scripts/run-long-claude-job.sh "
Perform comprehensive code analysis:
1. Review all components for performance issues
2. Identify security vulnerabilities  
3. Suggest architectural improvements
4. Generate detailed report with recommendations
"
```

#### Documentation Generation
```bash
./scripts/run-long-claude-job.sh "
Create comprehensive documentation:
1. Add JSDoc comments to all functions
2. Create API documentation
3. Write usage examples for components
4. Generate architecture diagrams
"
```

#### Testing Setup
```bash
./scripts/run-long-claude-job.sh "
Set up comprehensive testing infrastructure:
1. Configure Jest and testing libraries
2. Create test files for existing components
3. Set up E2E testing with Playwright
4. Add test coverage reporting
"
```

## 📚 Documentation

- **[MCP Setup Guide](docs/MCP_SETUP.md)** - Detailed MCP server configuration
- **[Long-Running Jobs](docs/LONG_RUNNING_JOBS.md)** - Job management and monitoring
- **[Dev Container Guide](docs/DEVCONTAINER_SETUP.md)** - Container configuration details
- **[Troubleshooting Guide](docs/TROUBLESHOOTING.md)** - Common issues and solutions

## 🔍 Monitoring and Debugging

### Check System Status

```bash
# Container status
docker-compose ps

# MCP server status
ps aux | grep mcp

# Claude processes
ps aux | grep claude

# Resource usage
docker stats
```

### Log Files

```bash
# MCP server logs
tail -f /tmp/mcp-server.log
tail -f /tmp/monday-mcp.log
tail -f /tmp/figma-mcp.log
tail -f /tmp/playwright-mcp.log

# Job logs
tail -f /workspace/claude-job-*.log

# Container logs
docker-compose logs -f claude-dev
```

### Health Checks

```bash
# Test MCP connections
claude mcp test filesystem
claude mcp test monday
claude mcp test playwright
claude mcp test figma

# Network connectivity
ping github.com
curl -I https://api.monday.com
```

## 🐛 Troubleshooting

### Common Issues

#### Container Won't Start
```bash
# Check Docker daemon
docker version

# Check disk space
df -h

# Rebuild container
docker-compose down
docker-compose build --no-cache
docker-compose up -d
```

#### MCP Servers Not Working
```bash
# Restart MCP servers
pkill -f mcp
./.devcontainer/init-mcp.sh

# Check environment variables
echo $MONDAY_API_TOKEN
echo $FIGMA_TOKEN

# Verify installations
npm list -g | grep mcp
```

#### Long-Running Jobs Failing
```bash
# Check Claude authentication
claude-code --version

# Verify permissions
ls -la /workspace

# Check available memory
free -m

# Review error logs
grep -i error /workspace/claude-job-*.log
```

### Getting Help

1. **Check logs** for specific error messages
2. **Review documentation** in the `docs/` directory
3. **Search issues** in the GitHub repository
4. **Create an issue** with:
   - Error messages
   - Steps to reproduce
   - Environment details (`docker version`, `node --version`)

## 🔒 Security Considerations

- **API Tokens**: Store in `.env` file, never commit to repository
- **Permissions**: Use `--dangerously-skip-permissions` only in trusted environments
- **Network**: Firewall rules are automatically configured
- **Container**: Runs with non-root user by default

## 🤝 Contributing

1. **Fork the repository**
2. **Create a feature branch:** `git checkout -b feature/amazing-feature`
3. **Make your changes** and test thoroughly
4. **Commit your changes:** `git commit -m 'Add amazing feature'`
5. **Push to the branch:** `git push origin feature/amazing-feature`
6. **Open a Pull Request**

### Development Guidelines

- Follow existing code style and conventions
- Add documentation for new features
- Test changes in both container and local environments
- Update relevant documentation files

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- **Anthropic** for Claude Code and MCP protocol
- **Microsoft** for VS Code Dev Containers
- **Docker** for containerization platform
- **Community contributors** for improvements and feedback

## 📞 Support

- **Documentation**: Check the `docs/` directory
- **Issues**: [GitHub Issues](https://github.com/your-username/claude-dev-setup/issues)
- **Discussions**: [GitHub Discussions](https://github.com/your-username/claude-dev-setup/discussions)

---

**Happy Coding with Claude! 🎉**