Skip to content

init/install fix #129

Closed
#132
Closed
init/install fix#129
#132
@polaz

Description

@polaz
polaz
opened on Jan 22, 2026

Problem

1. Duplicate Entries Bug

The client selection menu shows duplicate entries (e.g., "Claude Desktop" appears twice).

Root Cause Analysis:

  • src/cli/init/types.ts defines MCP_CLIENT_INFO with client metadata
  • src/cli/install/types.ts defines CLIENT_METADATA with overlapping data
  • Detection logic in detector.ts may return the same client via multiple detection methods (app-bundle + config-file fallback)

2. Fragmented Wizards

Current implementation has three separate wizards with duplicated logic:

  • gitlab-mcp init — GitLab connection setup only
  • gitlab-mcp install — Client installation only
  • gitlab-mcp docker — Docker deployment only

This creates user confusion and code duplication.

Solution: Unified Setup Wizard

Consolidate all wizards into a single gitlab-mcp setup command with clear branching structure.

Architecture Flow

┌─────────────────────────────────────────────────────────────────────┐
│                    GitLab MCP Setup Wizard                          │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ① DISCOVERY PHASE (automatic)                                      │
│     ├─ Detect installed MCP clients (Claude, Cursor, VSCode, etc.) │
│     ├─ Find existing gitlab-mcp configurations                     │
│     ├─ Check Docker environment (installed, running, container)    │
│     └─ Display summary:                                             │
│        "Found: Claude Code ✓, Cursor ✓, Docker running on :3333"   │
│                                                                      │
│  ② MODE SELECTION                                                   │
│     ┌─────────────────────────────────────────────────────────────┐ │
│     │ What would you like to do?                                  │ │
│     │                                                              │ │
│     │ ○ Configure existing (2 clients, 1 docker service)          │ │
│     │ ○ New local setup (stdio - for AI IDE clients)              │ │
│     │ ○ New server setup (HTTP/SSE - for shared/team access)      │ │
│     └─────────────────────────────────────────────────────────────┘ │
│                                                                      │
│  ③A: CONFIGURE EXISTING (when selected)                             │
│      ├─ Show list with actions:                                     │
│      │   ☑ Claude Code (configured)        [Update] [Remove]        │
│      │   ☐ Cursor (detected, not configured)  [Add]                 │
│      │   ☑ Docker :3333 (running)          [Update] [Stop]          │
│      └─ Execute selected actions                                    │
│                                                                      │
│  ③B: LOCAL SETUP (stdio mode)                                       │
│      ├─ GitLab instance: SaaS / Self-hosted                         │
│      ├─ Authentication method: PAT / OAuth                          │
│      │   └─ PAT: Enter token or open browser to create              │
│      ├─ Test connection → show username & GitLab version            │
│      │                                                               │
│      ├─ ④ TOOL CONFIGURATION                                        │
│      │   ┌───────────────────────────────────────────────────────┐  │
│      │   │ How do you want to configure tools?                   │  │
│      │   │                                                        │  │
│      │   │ ○ Use preset (recommended)                            │  │
│      │   │ ○ Select tools manually                               │  │
│      │   │ ○ Advanced settings                                   │  │
│      │   └───────────────────────────────────────────────────────┘  │
│      │                                                               │
│      │   ④A: USE PRESET                                             │
│      │       ├─ Select role/preset:                                 │
│      │       │   ○ Developer (issues, MRs, pipelines)              │
│      │       │   ○ Senior Developer (+ wiki, snippets, variables)  │
│      │       │   ○ DevOps (CI/CD focused)                          │
│      │       │   ○ Code Reviewer (MRs, discussions, approvals)     │
│      │       │   ○ Full Access (all features)                      │
│      │       │   ○ Read-Only (monitoring only)                     │
│      │       └─ Confirm read-only mode if applicable               │
│      │                                                               │
│      │   ④B: SELECT TOOLS MANUALLY                                  │
│      │       ├─ Show tool categories with checkboxes:               │
│      │       │   ☑ Core (projects, namespaces, users) [3 tools]    │
│      │       │   ☑ Merge Requests [4 tools]                        │
│      │       │   ☑ Pipelines & CI/CD [3 tools]                     │
│      │       │   ☐ Wiki [2 tools]                                  │
│      │       │   ☐ Snippets [2 tools]                              │
│      │       │   ☐ Webhooks & Integrations [3 tools]               │
│      │       │   ...                                                │
│      │       └─ Show total: "Selected: 23/47 tools"                │
│      │                                                               │
│      │   ④C: ADVANCED SETTINGS                                      │
│      │       ├─ All environment variables with current values       │
│      │       ├─ Grouped by category (see below)                     │
│      │       └─ Edit any value or keep defaults                     │
│      │                                                               │
│      └─ Install to clients (multiselect from detected)              │
│                                                                      │
│  ③C: SERVER SETUP (HTTP/SSE mode)                                   │
│      ├─ Deployment type:                                             │
│      │   ○ Docker standalone (stateless, for dev/testing)           │
│      │   ○ Docker + external PostgreSQL (production)                │
│      │   ○ Docker Compose bundle (postgres + gitlab-mcp together)   │
│      ├─ Port configuration (default: 3333)                          │
│      ├─ GitLab instances configuration (add one or more):           │
│      │   └─ Per instance: host, auth method, default preset         │
│      │                                                               │
│      ├─ ④ TOOL CONFIGURATION (same as Local Setup)                  │
│      │   ○ Use preset / Select manually / Advanced settings         │
│      │                                                               │
│      ├─ Generate config & start container                           │
│      └─ Optionally configure local clients to connect to server     │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

Advanced Settings - Environment Variables

When user selects "Advanced settings", show all configurable environment variables grouped by category:

┌─────────────────────────────────────────────────────────────────────┐
│                      Advanced Settings                              │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ▼ Connection                                                        │
│    GITLAB_URL           [https://gitlab.com    ]                    │
│    GITLAB_TOKEN         [glpat-************    ] (hidden)           │
│    GITLAB_API_VERSION   [v4                    ]                    │
│                                                                      │
│  ▼ Feature Flags (USE_*)                                            │
│    ☑ USE_ISSUES         Enable issues/work items                    │
│    ☑ USE_MRS            Enable merge requests                       │
│    ☑ USE_PIPELINES      Enable CI/CD pipelines                      │
│    ☑ USE_FILES          Enable file operations                      │
│    ☐ USE_WIKI           Enable wiki operations                      │
│    ☐ USE_SNIPPETS       Enable snippets                             │
│    ☐ USE_RELEASES       Enable releases                             │
│    ☐ USE_WEBHOOKS       Enable webhooks                             │
│    ☐ USE_INTEGRATIONS   Enable integrations                         │
│    ☐ USE_VARIABLES      Enable CI/CD variables                      │
│                                                                      │
│  ▼ Scope Restrictions                                               │
│    GITLAB_SCOPE_TYPE    [○ none ○ project ○ namespace]              │
│    GITLAB_SCOPE_PROJECT [                      ]                    │
│    GITLAB_SCOPE_NAMESPACE [                    ]                    │
│                                                                      │
│  ▼ Action Filtering                                                 │
│    GITLAB_DENIED_ACTIONS [                     ]                    │
│    GITLAB_READ_ONLY     [○ false ○ true       ]                     │
│                                                                      │
│  ▼ Customization                                                    │
│    GITLAB_MCP_PRESET    [developer ▼          ]                     │
│    GITLAB_MCP_PROFILE   [                      ]                    │
│    GITLAB_TOOL_*        [Edit descriptions... ]                     │
│    GITLAB_DESCRIPTION_* [Edit action descs... ]                     │
│                                                                      │
│  ▼ Transport & Server                                               │
│    TRANSPORT            [○ stdio ○ sse        ]                     │
│    PORT                 [3333                  ]                    │
│    TRUST_PROXY          [○ false ○ true       ]                     │
│                                                                      │
│  ▼ TLS/HTTPS                                                        │
│    SSL_CERT_PATH        [                      ]                    │
│    SSL_KEY_PATH         [                      ]                    │
│                                                                      │
│  ▼ OAuth (Server Mode Only)                                         │
│    OAUTH_ENABLED        [○ false ○ true       ]                     │
│    OAUTH_SESSION_SECRET [                      ]                    │
│    DATABASE_URL         [                      ]                    │
│                                                                      │
│  ▼ Logging                                                          │
│    LOG_LEVEL            [info ▼               ]                     │
│    LOG_FORMAT           [○ pretty ○ json      ]                     │
│                                                                      │
│  ▼ Proxy                                                            │
│    HTTP_PROXY           [                      ]                    │
│    HTTPS_PROXY          [                      ]                    │
│    NO_PROXY             [                      ]                    │
│                                                                      │
│  [Reset to Defaults]              [Preview Config]    [Apply]       │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

Tool Categories for Manual Selection

Category Tools Default
Core browse_projects, browse_namespaces, get_users ✅ Always
Merge Requests browse_merge_requests, manage_merge_request, browse_mr_discussions, manage_mr_discussion ✅ On
Work Items browse_work_items, manage_work_item ✅ On
Pipelines browse_pipelines, manage_pipeline, manage_pipeline_job ✅ On
Files browse_files, manage_files ✅ On
Commits browse_commits ✅ On
Refs browse_refs, manage_ref ☐ Off
Releases browse_releases, manage_release ☐ Off
Labels browse_labels, manage_label ☐ Off
Milestones browse_milestones, manage_milestone ☐ Off
Wiki browse_wiki, manage_wiki ☐ Off
Snippets browse_snippets, manage_snippet ☐ Off
Variables browse_variables, manage_variable ☐ Off
Webhooks list_webhooks, manage_webhook ☐ Off
Integrations list_integrations, manage_integration ☐ Off
Members browse_members, manage_member ☐ Off
Search browse_search ☐ Off
Context manage_context ☐ Off

Docker Deployment Options

Option Use Case Description
Standalone Development, testing gitlab-mcp container only, stateless, no persistence
+ External DB Production with existing PostgreSQL Container + DATABASE_URL for OAuth sessions
Full Bundle Production "all-in-one" docker-compose: postgres + gitlab-mcp together

Key Features

  1. Discovery First — Auto-detect environment before asking user to choose
  2. Smart Defaults — If existing configs found, offer "Configure existing" first
  3. Unified Entry Point — Single gitlab-mcp setup command for everything
  4. Flexible Tool Selection — Presets for quick setup, manual for power users
  5. Advanced Settings — Full control over all environment variables
  6. Non-destructive — Always preview changes before applying
  7. Backwards Compatible — init, install, docker init become aliases to setup

Implementation Plan

Phase 1: Fix Duplicate Bug & Consolidate Types

Files to modify:

  • src/cli/install/detector.ts — Fix duplicate detection logic
  • src/cli/install/types.ts — Remove CLIENT_METADATA, import from shared
  • src/cli/init/types.ts — Keep as single source of truth for client metadata

Changes:

  1. In detector.ts:detectClient() — ensure each client is detected only once
  2. Consolidate CLIENT_METADATA and MCP_CLIENT_INFO into single registry
  3. Add deduplication in detectAllClients() using Set

Phase 2: Create Unified Discovery Module

New files:

  • src/cli/setup/discovery.ts — Unified environment detection
  • src/cli/setup/types.ts — Shared types for setup wizard

DiscoveryResult structure:

interface DiscoveryResult {
  // MCP Clients
  clients: {
    detected: ClientInfo[];      // Installed clients
    configured: ClientInfo[];    // Clients with gitlab-mcp configured
    available: ClientInfo[];     // Not installed but supported
  };
  
  // Docker Environment
  docker: {
    installed: boolean;
    running: boolean;
    composeInstalled: boolean;
    container?: ContainerInfo;   // Running gitlab-mcp container
  };
  
  // Summary for display
  summary: {
    hasExistingSetup: boolean;
    clientCount: number;
    dockerRunning: boolean;
  };
}

Phase 3: Implement Tool Configuration Module

New files:

  • src/cli/setup/tool-config.ts — Tool selection logic
  • src/cli/setup/presets.ts — Preset definitions
  • src/cli/setup/advanced-settings.ts — All env var configuration

Tool categories:

interface ToolCategory {
  id: string;
  name: string;
  description: string;
  tools: string[];
  defaultEnabled: boolean;
}

interface ToolConfig {
  mode: 'preset' | 'manual' | 'advanced';
  preset?: string;
  enabledCategories?: string[];
  envOverrides?: Record<string, string>;
}

Phase 4: Implement Unified Wizard

New files:

  • src/cli/setup/wizard.ts — Main wizard orchestration
  • src/cli/setup/flows/local-setup.ts — Local (stdio) setup flow
  • src/cli/setup/flows/server-setup.ts — Server (HTTP/SSE) setup flow
  • src/cli/setup/flows/configure-existing.ts — Manage existing configs
  • src/cli/setup/flows/tool-selection.ts — Preset/manual/advanced flow
  • src/cli/setup/index.ts — Module exports

Wizard steps:

  1. Run discovery → display summary
  2. Mode selection (existing/local/server)
  3. GitLab authentication (if needed)
  4. Tool configuration (preset/manual/advanced)
  5. Client selection
  6. Execute actions with progress display
  7. Show completion summary

Phase 5: Refactor CLI Entry Point

Files to modify:

  • src/cli-utils.ts — Add setup command parsing
  • src/main.ts — Route setup command, make init/install aliases

Command mapping:

gitlab-mcp setup          → Unified wizard (new)
gitlab-mcp init           → Alias to: setup --mode=local
gitlab-mcp install        → Alias to: setup --mode=local --skip-gitlab
gitlab-mcp docker init    → Alias to: setup --mode=server

Phase 6: Reuse Existing Modules

Keep and reuse:

  • src/cli/init/connection.ts — GitLab connection testing
  • src/cli/init/config-generator.ts — Config generation
  • src/cli/init/browser.ts — Browser opening utility
  • src/cli/install/installers.ts — Client installation logic
  • src/cli/install/backup.ts — Config backup logic
  • src/cli/docker/docker-utils.ts — Docker operations

Deprecate (keep as re-exports for compatibility):

  • src/cli/init/wizard.ts — Replace with setup/flows/local-setup.ts
  • src/cli/install/install-command.ts — Replace with setup wizard
  • src/cli/docker/docker-command.ts:initDocker() — Replace with setup/flows/server-setup.ts

File Structure After Implementation

src/cli/
├── setup/                          # NEW: Unified setup wizard
│   ├── index.ts                    # Module exports
│   ├── types.ts                    # Shared types
│   ├── discovery.ts                # Environment detection
│   ├── wizard.ts                   # Main wizard orchestration
│   ├── tool-config.ts              # Tool selection logic
│   ├── presets.ts                  # Preset definitions
│   ├── advanced-settings.ts        # All env var configuration
│   └── flows/
│       ├── local-setup.ts          # stdio setup flow
│       ├── server-setup.ts         # HTTP/SSE setup flow
│       ├── configure-existing.ts   # Manage existing configs
│       └── tool-selection.ts       # Preset/manual/advanced flow
│
├── init/                           # KEEP: Reusable utilities
│   ├── index.ts
│   ├── types.ts                    # Single source of truth for client types
│   ├── connection.ts               # GitLab API connection
│   ├── config-generator.ts         # Config file generation
│   ├── browser.ts                  # Browser utilities
│   └── wizard.ts                   # DEPRECATED: Re-export for compatibility
│
├── install/                        # KEEP: Reusable utilities
│   ├── index.ts
│   ├── types.ts                    # Import from init/types.ts
│   ├── detector.ts                 # Client detection (FIXED)
│   ├── installers.ts               # Installation logic
│   ├── backup.ts                   # Backup utilities
│   └── install-command.ts          # DEPRECATED: Re-export for compatibility
│
├── docker/                         # KEEP: Reusable utilities
│   ├── index.ts
│   ├── types.ts
│   ├── docker-utils.ts             # Docker operations
│   └── docker-command.ts           # DEPRECATED: Some functions re-exported
│
└── utils/
    ├── index.ts
    └── path-utils.ts

Acceptance Criteria

Must Have

  • No duplicate entries in any selection menu
  • Single entry point: gitlab-mcp setup launches unified wizard
  • Discovery phase: Auto-detect clients, configs, and Docker before prompting
  • Three main flows: Configure existing, Local setup, Server setup
  • Tool configuration: Preset selection OR manual tool selection
  • Advanced settings: Full env var configuration UI
  • Backwards compatibility: init, install, docker init still work (as aliases)
  • All existing tests pass after refactoring
  • Test coverage ≥85% for all new code in src/cli/setup/

Should Have

  • Smart default selection based on discovery results
  • Preview of changes before applying (especially in advanced settings)
  • Clear progress indication during operations
  • Helpful error messages with recovery suggestions
  • Tool category descriptions and tool counts

Nice to Have

  • Detect and offer to fix misconfigured clients
  • Support for multiple GitLab instances in local setup
  • Import existing token from environment variables
  • Config export/import for team sharing
  • Dry-run mode for all operations

Testing Requirements

Unit Tests (≥85% coverage)

  • src/cli/setup/discovery.test.ts — Discovery logic
  • src/cli/setup/wizard.test.ts — Wizard flow orchestration
  • src/cli/setup/tool-config.test.ts — Tool selection logic
  • src/cli/setup/presets.test.ts — Preset definitions
  • src/cli/setup/advanced-settings.test.ts — Env var configuration
  • src/cli/setup/flows/*.test.ts — Individual flow tests

Integration Tests

  • Full wizard flow with mocked prompts
  • Client detection across platforms
  • Docker deployment configuration
  • Tool category enable/disable

Test Commands

# Run all tests with coverage
yarn test --coverage

# Run setup module tests only
yarn test src/cli/setup/

# Check coverage threshold
yarn test --coverage --coverageThreshold='{"src/cli/setup/**/*.ts": {"lines": 85}}'

Environment Variables Reference

Connection

Variable Description Default
GITLAB_URL GitLab instance URL https://gitlab.com
GITLAB_TOKEN Personal Access Token (required)
GITLAB_API_VERSION API version v4

Feature Flags

Variable Description Default
USE_ISSUES Enable issues/work items true
USE_MRS Enable merge requests true
USE_PIPELINES Enable pipelines true
USE_FILES Enable file operations true
USE_WIKI Enable wiki false
USE_SNIPPETS Enable snippets false
USE_RELEASES Enable releases false
USE_WEBHOOKS Enable webhooks false
USE_INTEGRATIONS Enable integrations false
USE_VARIABLES Enable CI/CD variables false

Scope & Filtering

Variable Description Default
GITLAB_SCOPE_PROJECT Restrict to single project (none)
GITLAB_SCOPE_NAMESPACE Restrict to namespace (none)
GITLAB_DENIED_ACTIONS Comma-separated denied actions (none)
GITLAB_READ_ONLY Enable read-only mode false

Presets & Profiles

Variable Description Default
GITLAB_MCP_PRESET Built-in preset name (none)
GITLAB_MCP_PROFILE User profile name (none)

Transport & Server

Variable Description Default
TRANSPORT Transport mode stdio
PORT HTTP server port 3333
TRUST_PROXY Trust reverse proxy headers false

TLS/HTTPS

Variable Description Default
SSL_CERT_PATH Path to SSL certificate (none)
SSL_KEY_PATH Path to SSL private key (none)

OAuth

Variable Description Default
OAUTH_ENABLED Enable OAuth mode false
OAUTH_SESSION_SECRET Session encryption secret (required if OAuth)
DATABASE_URL Database for sessions (required if OAuth)

Logging

Variable Description Default
LOG_LEVEL Log level info
LOG_FORMAT Log format pretty

Proxy

Variable Description Default
HTTP_PROXY HTTP proxy URL (none)
HTTPS_PROXY HTTPS proxy URL (none)
NO_PROXY Proxy bypass list (none)

Migration Notes

For Users

  • gitlab-mcp setup is the new recommended command
  • Existing init, install, docker init commands continue to work
  • No changes to existing configuration files
  • New "Advanced settings" provides full control over all options

For Developers

  • New code goes in src/cli/setup/
  • Reuse existing utilities from init/, install/, docker/
  • Follow existing patterns for @clack/prompts usage
  • Maintain backwards compatibility exports
  • All env vars must be documented in advanced-settings.ts

Related Issues

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions