Summary

Add --export flag to yarn list-tools that generates a complete TOOLS.md file from discriminated union schemas. This ensures documentation is always in sync with code.

Motivation

Current documentation is manually maintained and frequently out of sync with actual code:

• README claims 61 tools, but only 39 exist
• Tool names in docs do not match actual CQRS tool names
• Actions within CQRS tools are not documented

Auto-generating TOOLS.md from code eliminates this problem permanently.

Proposed Usage

# Generate TOOLS.md to stdout
yarn list-tools --export

# Generate TOOLS.md to file
yarn list-tools --export > docs/TOOLS.md

# Generate with custom options
yarn list-tools --export --no-examples  # Skip example JSON blocks
yarn list-tools --export --toc          # Include table of contents

Output Format

# GitLab MCP Tools Reference

> Auto-generated from source code. Do not edit manually.
> Generated: 2025-01-20 | Tools: 39 | Version: 6.x.x

## Table of Contents
- [Core Tools (13)](#core-tools)
- [Labels Management (2)](#labels-management)
- ...

---

## Core Tools

### browse_projects

PROJECT DISCOVERY: Find, browse, or inspect GitLab projects.

#### Actions

| Action | Description |
|--------|-------------|
| `search` | Find projects by name/topic across all GitLab |
| `list` | Browse your accessible projects or projects within a group |
| `get` | Retrieve full details of a known project |

#### Parameters

| Parameter | Type | Required | Actions | Description |
|-----------|------|----------|---------|-------------|
| `action` | enum | Yes | all | Action: search, list, get |
| `project_id` | string | Yes* | get | Project ID (required for get) |
| `q` | string | No | search | Search query |
| `group_id` | string | No | list | Group to list projects from |
| ... | | | | |

#### Example

```json
{
  "action": "list",
  "group_id": "mygroup",
  "per_page": 20
}

browse_labels

BROWSE labels with listing and retrieval.

Actions

Parameters

...

## Implementation Details

### 1. Parse Discriminated Union Schemas

For CQRS tools, extract actions from `oneOf` or flattened `action` enum:

```typescript
function extractActions(schema: JsonSchema): ActionInfo[] {
  // Handle discriminated union (oneOf with action literals)
  if (schema.oneOf) {
    return schema.oneOf.map(branch => ({
      name: branch.properties.action.const,
      description: branch.description,
      requiredParams: branch.required,
      optionalParams: Object.keys(branch.properties).filter(...)
    }));
  }
  
  // Handle flattened schema (action enum)
  if (schema.properties?.action?.enum) {
    return schema.properties.action.enum.map(action => ({
      name: action,
      description: extractActionDescription(schema, action)
    }));
  }
  
  return []; // Non-CQRS tool
}

2. Group Parameters by Action

Show which parameters apply to which actions:

function getParameterActions(schema: JsonSchema, paramName: string): string[] {
  // For discriminated unions, check which branches include this param
  // For flattened schemas, parse from description or assume "all"
}

3. Fix groupToolsByEntity

Current implementation uses outdated regex patterns. Replace with:

function groupToolsByEntity(tools: Tool[]): Map<string, Tool[]> {
  const entityMap: Record<string, string[]> = {
    "Core": ["browse_projects", "browse_namespaces", "browse_commits", ...],
    "Labels": ["browse_labels", "manage_label"],
    "Wiki": ["browse_wiki", "manage_wiki"],
    "Milestones": ["browse_milestones", "manage_milestone"],
    "Pipelines": ["browse_pipelines", "manage_pipeline", "manage_pipeline_job"],
    // ... etc
  };
  
  // Or better: read from registry metadata
}

4. Add Version and Timestamp

Include generation metadata:

const header = `
# GitLab MCP Tools Reference

> Auto-generated from source code. Do not edit manually.
> Generated: ${new Date().toISOString()} | Tools: ${tools.length} | Version: ${pkg.version}
`;

Tasks

• Add --export flag to CLI argument parser
• Implement extractActions() for discriminated unions
• Implement getParameterActions() for per-action params
• Fix groupToolsByEntity() with current tool names
• Generate markdown table of contents
• Generate action tables for each CQRS tool
• Generate parameter tables with action applicability
• Generate example JSON for each tool
• Add header with generation timestamp and version
• Add --no-examples flag option
• Add --toc flag for table of contents
• Update docs issue docs: Critical documentation refactor - fix 22 missing tools and outdated entity descriptions #24 to use yarn list-tools --export

CI Integration (Future)

# .github/workflows/docs.yml
- name: Generate TOOLS.md
  run: yarn list-tools --export > docs/TOOLS.md

- name: Check for changes
  run: |
    git diff --exit-code docs/TOOLS.md || \
      echo "::error::TOOLS.md is out of sync. Run yarn list-tools --export"

Acceptance Criteria

• yarn list-tools --export produces valid markdown
• All 39 tools are documented
• All CQRS actions are listed with descriptions
• Parameters show which actions they apply to
• Each tool has at least one example
• Output can be redirected to file
• Generation is deterministic (same output for same code)

Priority

HIGH - Prerequisite for documentation refactor (#24). Solves sync problem permanently.

Related

• docs: Critical documentation refactor - fix 22 missing tools and outdated entity descriptions #24 - Documentation refactor (will use this tool)