Summary

Iterative documentation refactor: migrate README.md content to VitePress static site on GitHub Pages, following MCP documentation best practices.

Current State Analysis:

• README: 1122 lines, claims 62 tools
• Reality: 47 tools (post-CQRS consolidation)
• Existing: docs/TOOLS.md auto-generated, docs/setup-github-secrets.md, docs/public/CNAME

Iterative Process

Workflow for Each Section

┌─────────────────────────────────────────────────────────────────┐
│                    DOCUMENTATION ITERATION                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  1. EXTRACT section from README                                  │
│     └── Identify lines, topic, target page                       │
│                                                                  │
│  2. VERIFY against actual code                                   │
│     └── Check if feature exists, behavior matches                │
│     └── Run yarn list-tools, check schemas, test endpoints       │
│                                                                  │
│  3. DECISION POINT                                               │
│     ├── Code matches docs → Write documentation                  │
│     ├── Docs outdated → Update docs to match code                │
│     └── Code needs improvement → Create spin-off issue           │
│                                                                  │
│  4. WRITE documentation page                                     │
│     └── VitePress markdown in docs/ directory                    │
│                                                                  │
│  5. REMOVE processed content from README                         │
│     └── Leave only link to new location                          │
│                                                                  │
│  6. REPEAT until README is minimal (<200 lines)                  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Spin-off Issue Protocol

When documentation reveals code problems:

1. Identify the issue type:

   • 🐛 Bug: Code doesn't work as expected
   • 🎯 UX: Works but confusing for users
   • 📚 Gap: Feature missing documentation hooks
   • ⚠️ Inconsistency: Behavior differs from similar features

2. Create independent issue:

   • Clear title: fix(entity): specific problem
   • Reproduction steps or code location
   • Expected vs actual behavior
   • Link back to docs: Critical documentation refactor - fix 22 missing tools and outdated entity descriptions #24 as context

3. Document "as it should be":

   • Write documentation for ideal behavior
   • Note: "Implementation: see #XXX"
   • Continue with next section

README Section Breakdown

Phase 1: VitePress Foundation

• Add VitePress dependency and config
• Create docs/.vitepress/config.ts
• Set up GitHub Pages workflow
• Create home page hero
• Add MCP Install Badges to home page hero (see MCP Install Badges section below)

Phase 2: Installation & Quick Start (Lines 22-188)

Verification checklist:

• Test npx @structured-world/gitlab-mcp actually works
• Verify Docker image exists at ghcr.io/structured-world/gitlab-mcp:latest
• Check all env vars mentioned are still valid
• Verify USE_* flags list is complete
• Test MCP install deeplinks work in VS Code, Cursor

Phase 3: Auto-Discovery (Lines 190-238)

Verification checklist:

• Test --auto flag behavior
• Verify --dry-run output
• Check priority order is accurate

Phase 4: Transport Modes (Lines 239-264)

Verification checklist:

• Test PORT env triggers HTTP mode
• Verify /sse and /mcp endpoints exist
• Test stdio argument override

Phase 5: TLS/HTTPS (Lines 265-295)

Verification checklist:

• Test SSL_CERT_PATH and SSL_KEY_PATH work
• Link to existing SSL.md if detailed

Phase 6: OAuth Authentication (Lines 297-509) ⚠️ COMPLEX

⚠️ PRESERVE: ASCII diagram (lines 425-438) must be kept exactly!

Verification checklist:

• Test OAUTH_ENABLED=true startup
• Verify all OAuth endpoints exist
• Test device flow works
• Check GitLab 17.1+ requirement accuracy

Phase 7: Environment Variables (Lines 510-539)

Verification checklist:

• Run yarn list-tools --env to get accurate env var list
• Verify each USE_* flag enables correct tools
• Check default values are accurate

Phase 8: Dynamic Descriptions (Lines 540-603)

Verification checklist:

• Test GITLAB_TOOL_* actually works
• Verify tool count in notes (says 59, should be 47)

Phase 9: Action Filtering (Lines 604-735)

Verification checklist:

• Test GITLAB_DENIED_ACTIONS filtering
• Verify schema actually shrinks with denied actions

Phase 10: Tools Reference (Lines 736-934) ⚠️ OUTDATED

STATUS: MUST BE DELETED

Current README claims:

• "62 Tools Available" ❌ Reality: 47
• Lists 5 Label tools ❌ Reality: 2 CQRS
• Lists 9 Milestone tools ❌ Reality: 2 CQRS
• Lists 12 Pipeline tools ❌ Reality: 3 CQRS
• Lists 5 Wiki tools ❌ Reality: 2 CQRS

Action:

• Delete entire section
• Replace with link to auto-generated /tools/ or TOOLS.md
• Ensure yarn list-tools --export is accurate

Phase 11: CLI Tools (Lines 935-1040)

Verification checklist:

• Test all yarn list-tools commands
• Verify --entity, --tool, --json flags work

Phase 12: Testing Section (Lines 1041-1086)

Action: Move to CONTRIBUTING.md (developer documentation, not user-facing)

Phase 13: Footer (Lines 1087-1122)

VitePress Configuration

// docs/.vitepress/config.ts
import { defineConfig } from 'vitepress';

export default defineConfig({
  title: 'GitLab MCP',
  description: 'Model Context Protocol server for GitLab API',
  base: '/gitlab-mcp/',

  themeConfig: {
    nav: [
      { text: 'Guide', link: '/guide/' },
      { text: 'Tools', link: '/tools/' },
      { text: 'Security', link: '/security/' },
      { text: 'Advanced', link: '/advanced/' },
    ],

    sidebar: {
      '/guide/': [
        { text: 'Quick Start', link: '/guide/quick-start' },
        { text: 'Installation', collapsed: false, items: [
          { text: 'npm/npx', link: '/guide/installation/npm' },
          { text: 'Docker', link: '/guide/installation/docker' },
          { text: 'VS Code', link: '/guide/installation/vscode' },
          { text: 'Codex', link: '/guide/installation/codex' },
        ]},
        { text: 'Configuration', link: '/guide/configuration' },
      ],
      '/security/': [
        { text: 'OAuth', link: '/security/oauth' },
        { text: 'Token Safety', link: '/security/tokens' },
        { text: 'Read-Only Mode', link: '/security/read-only' },
      ],
      '/advanced/': [
        { text: 'TLS/HTTPS', link: '/advanced/tls' },
        { text: 'Customization', link: '/advanced/customization' },
        { text: 'Profiles & Presets', link: '/advanced/profiles' },
      ],
    },

    search: { provider: 'local' },
  },
});

GitHub Actions

# .github/workflows/docs.yml
name: Deploy Documentation

on:
  push:
    branches: [main]
    paths:
      - 'docs/**'
      - 'src/**'  # for coverage integration
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
          cache: yarn
      - run: yarn install --frozen-lockfile
      - run: yarn docs:build
      - run: yarn test:cov
      - run: cp -r coverage/lcov-report docs/.vitepress/dist/coverage
      - uses: actions/upload-pages-artifact@v3
        with:
          path: docs/.vitepress/dist

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/deploy-pages@v4
        id: deployment

MCP Install Badges (One-Click Installation)

Overview

MCP Install Badges provide one-click installation experience for users. When clicked, these badges open the IDE and automatically configure gitlab-mcp as an MCP server.

Supported IDEs and Deeplink Formats

Implementation Options

Option A: Static Badges in README (Simplest)

Add manually crafted badges to README.md header:

<!-- One-Click Install Badges -->
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_GitLab_MCP-007ACC?style=for-the-badge&logo=visualstudiocode&logoColor=white)](vscode:mcp/install?name=gitlab-mcp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40structured-world%2Fgitlab-mcp%22%5D%7D)

[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=gitlab-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBzdHJ1Y3R1cmVkLXdvcmxkL2dpdGxhYi1tY3AiXX0=)

Pros: Simple, no CI needed, works immediately
Cons: Config is URL-encoded/base64, hard to maintain, no version pinning

Option B: Generate Badges in CI (Recommended)

Add badge generation step to release workflow:

# .github/workflows/release.yml (add to existing)
- name: Generate MCP Install Badges
  run: |
    VERSION=${{ github.ref_name }}

    # VS Code config (URL-encoded JSON)
    VSCODE_CONFIG=$(node -e "console.log(encodeURIComponent(JSON.stringify({
      command: 'npx',
      args: ['-y', '@structured-world/gitlab-mcp@${VERSION}']
    })))")

    # Cursor config (base64-encoded JSON)
    CURSOR_CONFIG=$(echo -n '{"command":"npx","args":["-y","@structured-world/gitlab-mcp@'${VERSION}'"]}' | base64 -w0)

    # Generate badges markdown
    cat > docs/public/install-badges.md << EOF
    ## One-Click Install

    [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-007ACC?style=for-the-badge&logo=visualstudiocode)](vscode:mcp/install?name=gitlab-mcp&config=${VSCODE_CONFIG})

    [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=gitlab-mcp&config=${CURSOR_CONFIG})
    EOF

- name: Update README badges
  run: |
    # Script to update README.md badge section with latest version
    ./scripts/update-badges.sh ${{ github.ref_name }}

Pros: Version-pinned badges, auto-updated on release, maintainable
Cons: Requires CI setup, badges update only on release

Option C: Interactive Badge Generator Page on VitePress (Best UX)

Create a dedicated page on the documentation site:

docs/
└── install/
    └── index.md    # Interactive badge generator

docs/install/index.md:

# One-Click Install

<script setup>
import InstallBadges from '../.vitepress/components/InstallBadges.vue'
</script>

<InstallBadges />

## Manual Installation

If one-click install doesn't work, see [manual installation guide](/guide/installation/).

docs/.vitepress/components/InstallBadges.vue:

<template>
  <div class="install-badges">
    <div class="badge-row">
      <a :href="vscodeUrl" class="badge">
        <img src="https://img.shields.io/badge/VS_Code-Install-007ACC?style=for-the-badge&logo=visualstudiocode" />
      </a>
      <a :href="cursorUrl" class="badge">
        <img src="https://cursor.com/deeplink/mcp-install-dark.svg" />
      </a>
    </div>

    <details>
      <summary>Customize installation</summary>
      <div class="options">
        <label>
          <input type="checkbox" v-model="pinVersion" />
          Pin to version {{ latestVersion }}
        </label>
        <label>
          GitLab URL: <input v-model="gitlabUrl" placeholder="https://gitlab.com" />
        </label>
      </div>
    </details>

    <div class="copy-section">
      <h3>Copy badge markdown for your project:</h3>
      <pre><code>{{ badgeMarkdown }}</code></pre>
      <button @click="copy">Copy</button>
    </div>
  </div>
</template>

<script>
export default {
  data() {
    return {
      latestVersion: '6.29.1', // Fetched from npm or hardcoded
      pinVersion: false,
      gitlabUrl: ''
    }
  },
  computed: {
    config() {
      const pkg = this.pinVersion
        ? `@structured-world/gitlab-mcp@${this.latestVersion}`
        : '@structured-world/gitlab-mcp';
      return {
        command: 'npx',
        args: ['-y', pkg],
        ...(this.gitlabUrl && { env: { GITLAB_URL: this.gitlabUrl } })
      };
    },
    vscodeUrl() {
      return `vscode:mcp/install?name=gitlab-mcp&config=${encodeURIComponent(JSON.stringify(this.config))}`;
    },
    cursorUrl() {
      return `cursor://anysphere.cursor-deeplink/mcp/install?name=gitlab-mcp&config=${btoa(JSON.stringify(this.config))}`;
    },
    badgeMarkdown() {
      return `[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-007ACC?logo=visualstudiocode)](${this.vscodeUrl})`;
    }
  }
}
</script>

Pros: Best UX, customizable, always current version, copy-paste for users
Cons: Requires Vue component, more complex setup

Recommended Implementation Plan

Badge Configuration Reference

VS Code / VS Code Insiders:

vscode:mcp/install?name=<server-name>&config=<url-encoded-json>

Config JSON structure:

{
  "command": "npx",
  "args": ["-y", "@structured-world/gitlab-mcp"],
  "env": {
    "GITLAB_URL": "https://gitlab.com"  // optional
  }
}

Cursor:

cursor://anysphere.cursor-deeplink/mcp/install?name=<server-name>&config=<base64-encoded-json>

Same config JSON, but base64-encoded instead of URL-encoded.

Testing Badges

Before deploying, test badges work:

1. VS Code: Click badge, should open VS Code with MCP install prompt
2. Cursor: Click badge, should open Cursor with config dialog
3. Verify config: After install, check ~/.vscode/mcp.json or ~/.cursor/mcp.json

External Resources

• MCP Badge Creator - Interactive badge generator
• VSCodeMCP.com - VS Code specific badge generator
• Cursor Install Links Docs - Official Cursor deeplink format

Acceptance Criteria

• VitePress site deployed to GitHub Pages
• README reduced to <200 lines (overview + links)
• All sections migrated to appropriate /docs/ pages
• Tools section removed, replaced with link to TOOLS.md
• No outdated tool counts (62->47 corrected everywhere)
• OAuth ASCII diagram preserved exactly
• Spin-off issues created for discovered code problems
• Search works across documentation
• Coverage integrated at /coverage/
• CONTRIBUTING.md created with testing docs
• MCP Install Badges added to README header
• MCP Install Badges added to VitePress home page
• Badge deeplinks tested in VS Code and Cursor

Related Issues

Track spin-off issues here as they are created:

• docs: Prompt Library and advanced site features (Phase 2) #125 - docs: Prompt Library and advanced site features (Phase 2)

References

• 5 Examples of Excellent MCP Documentation
• VitePress Documentation
• Current TOOLS.md - auto-generated, 47 tools
• MCP Badge Creator - Interactive badge generator
• VSCodeMCP.com - VS Code MCP install button generator
• Cursor Install Links Docs - Official Cursor deeplink documentation
• VS Code MCP Servers - VS Code MCP documentation