Summary

Extracted from #62 - MCP client installation support and Docker OAuth setup.

Phase 2: MCP Client Installation

Install configuration to various MCP clients.

Supported Clients

Commands

gitlab-mcp install --claude-desktop  # Claude Desktop (JSON config)
gitlab-mcp install --claude-code     # Claude Code (via `claude mcp add`)
gitlab-mcp install --cursor          # Cursor
gitlab-mcp install --vscode          # VS Code Copilot
gitlab-mcp install --cline           # Cline
gitlab-mcp install --roo-code        # Roo Code
gitlab-mcp install --windsurf        # Windsurf
gitlab-mcp install --all             # All detected clients
gitlab-mcp install --show            # Show config only

Tasks

• Detect installed MCP clients (src/cli/install/detector.ts)
• Claude Desktop config installer (JSON) (src/cli/install/installers.ts)
• Claude Code installer (via claude mcp add) (src/cli/install/installers.ts)
• Cursor config installer (src/cli/install/installers.ts)
• VS Code Copilot config installer (src/cli/install/installers.ts)
• Cline config installer (src/cli/install/installers.ts)
• Roo Code config installer (src/cli/install/installers.ts)
• Windsurf config installer (src/cli/install/installers.ts)
• Backup existing configs before modification (src/cli/install/backup.ts)
• Interactive install wizard (src/cli/install/install-command.ts)
• Increase test coverage to >86% for installers.ts (currently ~78%)

Phase 3: Docker + OAuth

For multi-GitLab setups with OAuth authentication.

Commands

gitlab-mcp docker status      # Container + instances status
gitlab-mcp docker logs        # Tail container logs
gitlab-mcp docker restart     # Restart container
gitlab-mcp docker upgrade     # Pull latest image + restart
gitlab-mcp docker stop        # Stop container
gitlab-mcp docker add-instance <host>  # Add GitLab instance

Docker Compose Template

# ~/.config/gitlab-mcp/docker-compose.yml
version: '3.8'
services:
  gitlab-mcp:
    image: ghcr.io/structured-world/gitlab-mcp:latest
    container_name: gitlab-mcp
    ports:
      - "${PORT:-3333}:3333"
    environment:
      - TRANSPORT=sse
      - PORT=3333
      - OAUTH_ENABLED=true
      - OAUTH_SESSION_SECRET=${OAUTH_SESSION_SECRET}
      - DATABASE_URL=file:/data/sessions.db
    volumes:
      - gitlab-mcp-data:/data
      - ./instances.yml:/app/config/instances.yml:ro
    restart: unless-stopped

volumes:
  gitlab-mcp-data:

Multi-Instance Configuration

# ~/.config/gitlab-mcp/instances.yml
instances:
  gitlab.com:
    name: "GitLab.com"
    oauth:
      client_id: "abc123"
      client_secret_env: "GITLAB_COM_SECRET"
    default_preset: "gitlab-com"

  gitlab.company.com:
    name: "Company GitLab"
    oauth:
      client_id: "xyz789"
      client_secret_env: "GITLAB_COMPANY_SECRET"
    default_preset: "developer"

Tasks

• Docker detection (src/cli/docker/docker-utils.ts)
• docker-compose.yml generation (src/cli/docker/types.ts)
• Container startup/management (src/cli/docker/docker-utils.ts)
• Multi-instance configuration (src/cli/docker/docker-utils.ts)
• gitlab-mcp docker subcommands (src/cli/docker/docker-command.ts)
• OAuth flow testing (requires running container)
• Increase test coverage to >86% for docker-utils.ts (currently ~63%)

Related Fixes

Milestone ID vs IID clarification

During implementation, we investigated the GitLab Milestones API to clarify the milestone_id parameter:

• GitLab API uses global ID (the id field from API response) in URL paths, NOT the IID
• This differs from issues/MRs which use IID in URLs
• API response contains both id (global unique) and iid (project/group-scoped)
• Updated schema descriptions to clarify this for AI agents
• Files changed: src/entities/milestones/schema-readonly.ts, src/entities/milestones/schema.ts

Dependencies

• feat(cli): Interactive setup wizard (gitlab-mcp init) #62 - Core wizard (Phase 1) ✅
• feat: Profiles infrastructure - base support for named configuration profiles #54 - Profiles infrastructure ✅
• feat: Built-in role-based profiles (junior-dev, senior-dev, devops, team-lead, pm, admin, ci, readonly) #55 - Built-in presets ✅

Implementation Status

Phase 2 (Install): ✅ Complete (needs coverage improvement)
Phase 3 (Docker): ✅ Complete (needs coverage improvement + OAuth testing)