Summary

Phase 3 of documentation refactor - comprehensive documentation for the new Unified Setup Wizard (gitlab-mcp setup) and all CLI commands.

Depends on:

• docs: Critical documentation refactor - fix 22 missing tools and outdated entity descriptions #24 (VitePress foundation + README migration) ✅ Done - VitePress site exists with guide/, cli/, security/, advanced/ sections
• init/install fix #129 (Unified Setup Wizard implementation)

Context

After implementing the Unified Setup Wizard (#129), users need clear documentation covering:

1. Getting Started - First-time setup experience
2. CLI Reference - All commands and flags
3. Installation Guides - Per-client setup instructions
4. Deployment Options - Local vs Server vs Docker
5. Troubleshooting - Common issues and solutions

Current Documentation State

The VitePress docs site already exists with this structure:

docs/
├── index.md                        # Main landing page
├── TOOLS.md                        # Auto-generated tool reference
├── guide/
│   ├── index.md                    # Guide overview
│   ├── quick-start.md              # Quick start guide
│   ├── configuration.md            # Configuration reference
│   ├── auto-discovery.md           # Auto-discovery feature
│   ├── transport.md                # Transport modes
│   └── installation/
│       ├── npm.md                  # npm/npx installation
│       ├── docker.md               # Docker installation
│       ├── codex.md                # Codex installation
│       └── vscode.md               # VS Code installation
├── cli/
│   └── list-tools.md               # list-tools command
├── security/
│   ├── oauth.md                    # OAuth setup
│   └── read-only.md                # Read-only mode
├── advanced/
│   ├── customization.md            # Customization options
│   └── tls.md                      # TLS configuration
└── tools/
    └── index.md                    # Tools overview

Proposed New Documentation

New files to create:

docs/
├── guide/
│   └── installation/
│       ├── index.md                # Installation overview (hub page)
│       ├── wizard.md               # Interactive setup wizard
│       └── manual.md               # Manual configuration
│
├── cli/
│   ├── index.md                    # CLI overview
│   ├── setup.md                    # gitlab-mcp setup command
│   ├── init.md                     # gitlab-mcp init (alias)
│   ├── install.md                  # gitlab-mcp install (alias)
│   └── docker.md                   # gitlab-mcp docker commands
│
├── clients/
│   ├── index.md                    # Supported clients overview
│   ├── claude-desktop.md           # Claude Desktop setup
│   ├── claude-code.md              # Claude Code (CLI) setup
│   ├── cursor.md                   # Cursor setup
│   ├── vscode.md                   # VS Code + GitHub Copilot
│   ├── windsurf.md                 # Windsurf setup
│   ├── cline.md                    # Cline setup
│   └── roo-code.md                 # Roo Code setup
│
├── deployment/
│   ├── index.md                    # Deployment options overview
│   ├── local-stdio.md              # Local stdio mode
│   ├── docker-standalone.md        # Docker without persistence
│   ├── docker-postgres.md          # Docker + external PostgreSQL
│   └── docker-compose.md           # Docker Compose bundle
│
└── troubleshooting/
    ├── index.md                    # Common issues
    ├── connection.md               # GitLab connection issues
    ├── clients.md                  # Client-specific issues
    └── docker.md                   # Docker issues

Existing files to update:

• docs/guide/quick-start.md - Add wizard reference, update prerequisites
• docs/guide/installation/npm.md - Cross-link to wizard
• docs/guide/installation/docker.md - Cross-link to deployment section
• docs/cli/list-tools.md - Align format with new CLI docs

Detailed Sections

1. Quick Start Update (docs/guide/quick-start.md)

Changes needed:

• Add gitlab-mcp setup as primary getting-started command
• Update prerequisites (Node.js 24+, GitLab PAT)
• Add verification steps

2. Setup Wizard (docs/cli/setup.md)

Content:

• Complete wizard flow documentation
• All mode options (existing/local/server)
• Flags and arguments
• Examples for each flow

Sections:

3. Client Configuration Guides

One page per client with:

• Requirements
• Auto-detection criteria
• Config file location (per OS)
• Manual configuration example
• Verification steps
• Client-specific notes

4. Deployment Options (docs/deployment/)

Local stdio (local-stdio.md):

• When to use (single user, IDE client)
• Configuration
• Limitations

Docker Standalone (docker-standalone.md):

• When to use (development, testing)
• Quick start command
• Environment variables
• Limitations (no persistence)

Docker + PostgreSQL (docker-postgres.md):

• When to use (production, multiple users)
• DATABASE_URL configuration
• OAuth session storage
• Scaling considerations

Docker Compose Bundle (docker-compose.md):

• When to use (all-in-one production)
• Complete docker-compose.yml
• Volume configuration
• Backup procedures

5. CLI Reference (docs/cli/)

Commands:

6. Troubleshooting (docs/troubleshooting/)

Common Issues:

Tasks

New Files (Create)

• Create docs/guide/installation/index.md (installation hub page)
• Create docs/guide/installation/wizard.md (interactive wizard guide)
• Create docs/guide/installation/manual.md (manual configuration)
• Create docs/cli/index.md (CLI overview)
• Create docs/cli/setup.md (main setup command)
• Create docs/cli/init.md (alias documentation)
• Create docs/cli/install.md (alias documentation)
• Create docs/cli/docker.md (docker subcommands)
• Create docs/clients/index.md (supported clients table)
• Create docs/clients/claude-desktop.md
• Create docs/clients/claude-code.md
• Create docs/clients/cursor.md
• Create docs/clients/vscode.md
• Create docs/clients/windsurf.md
• Create docs/clients/cline.md
• Create docs/clients/roo-code.md
• Create docs/deployment/index.md (comparison table)
• Create docs/deployment/local-stdio.md
• Create docs/deployment/docker-standalone.md
• Create docs/deployment/docker-postgres.md
• Create docs/deployment/docker-compose.md
• Create docs/troubleshooting/index.md
• Create docs/troubleshooting/connection.md
• Create docs/troubleshooting/clients.md
• Create docs/troubleshooting/docker.md

Existing Files (Update)

• Update docs/guide/quick-start.md - add wizard reference
• Update docs/guide/installation/npm.md - cross-link wizard
• Update docs/guide/installation/docker.md - cross-link deployment
• Update docs/cli/list-tools.md - align format with new CLI docs

VitePress Config

• Add CLI section to sidebar
• Add Clients section to sidebar
• Add Deployment section to sidebar
• Add Troubleshooting section to sidebar
• Add search keywords for common issues

Acceptance Criteria

Must Have

• Quick start guide gets user running in <5 minutes
• All CLI commands documented with flags table
• All 7 supported clients have dedicated pages
• All 4 deployment options documented
• Troubleshooting covers top 10 common issues
• All code examples tested and working

Should Have

• Copy-to-clipboard for all code blocks
• OS-specific tabs for config paths
• Search finds common issues quickly

Nice to Have

• Interactive config generator
• Client detection status checker
• Docker health check endpoint documentation

Related Issues

• docs: Critical documentation refactor - fix 22 missing tools and outdated entity descriptions #24 - docs: Critical documentation refactor (VitePress foundation) ✅ Done
• docs: Prompt Library and advanced site features (Phase 2) #125 - docs: Prompt Library and advanced site features (Phase 2)
• init/install fix #129 - fix: Unified Setup Wizard implementation

References

• Claude Desktop MCP Configuration
• VitePress Tabs Plugin
• Docusaurus CLI Reference Pattern