feat(docs): add --export flag to list-tools for TOOLS.md generation by polaz · Pull Request #51 · structured-world/gitlab-mcp

polaz · 2026-01-19T23:25:31Z

Summary

Add --export flag to generate complete TOOLS.md documentation
Add --toc flag for table of contents
Add --no-examples flag to skip example JSON blocks
Add getAllToolDefinitionsUnfiltered() method for documentation export (no env filtering)
Extract actions from CQRS schemas and display in tables
Include tier badges for tools with tier requirements

Usage

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

# Generate with table of contents
yarn list-tools --export --toc

# Generate without examples (more compact)
yarn list-tools --export --no-examples

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

Example Output

# GitLab MCP Tools Reference

> Auto-generated from source code. Do not edit manually.
> Generated: 2026-01-19 | Tools: 39 | Version: 6.8.0

## Core

### browse_projects

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

#### Actions

| Action | Description |
|--------|-------------|
| `search` | Search for items |
| `list` | List items with filtering and pagination |
| `get` | Get a single item by ID |

#### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `action` | string | Yes | Action to perform: search, list, get |
...

Test plan

yarn build passes
yarn lint passes
yarn test:unit passes (1780 tests)
yarn list-tools --export generates 39 tools
yarn list-tools --export --toc includes table of contents
yarn list-tools --export --no-examples skips JSON examples
Version correctly detected from package.json

Closes #47

Add documentation export capability to the list-tools CLI script: - Add --export flag to generate complete TOOLS.md markdown - Add --toc flag for table of contents - Add --no-examples flag to skip example JSON blocks - Add getAllToolDefinitionsUnfiltered() method to registry-manager for getting all tools without env filtering (for documentation) - Apply schema transformation to flatten discriminated unions - Include tier badges for tools with tier requirements - Extract actions from CQRS schemas and display in tables - Group tools by entity category (Core, Work Items, MRs, etc.) - Add version and timestamp to generated header Usage: yarn list-tools --export > docs/TOOLS.md yarn list-tools --export --toc --no-examples Closes #47

github-actions · 2026-01-19T23:26:34Z

📊 Test Coverage Report

Overall Coverage: 87.14%

Coverage Details

Metric	Percentage
Statements	87.14%
Branches	79.38%
Functions	73.18%
Lines	87.66%

Coverage Report: View detailed coverage report

This report was generated automatically from your PR changes.

codecov · 2026-01-19T23:27:23Z

Codecov Report

❌ Patch coverage is 87.11944% with 55 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/cli/list-tools.ts	86.18%	15 Missing and 40 partials ⚠️

📢 Thoughts on this report? Let us know!

Copilot

Pull request overview

This PR adds documentation export functionality to the list-tools CLI, enabling automated generation of TOOLS.md reference documentation with configurable options. The implementation includes extracting CQRS action definitions, displaying tier requirements, and providing flexible output formats.

Changes:

Added getAllToolDefinitionsUnfiltered() method to bypass environment filtering for documentation generation
Implemented comprehensive documentation export with --export, --toc, and --no-examples flags
Moved list-tools from src/scripts/ to src/ root directory

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.

File	Description
src/registry-manager.ts	Added getAllToolDefinitionsUnfiltered() method to return all tool definitions without environment variable filtering for documentation purposes
src/list-tools.ts	New comprehensive CLI tool for listing and exporting tool documentation with multiple output formats, action extraction, and tier badge support
package.json	Updated script paths to reflect file relocation from src/scripts/ to src/

src/list-tools.ts

src/cli/list-tools.ts

src/list-tools.ts

src/registry-manager.ts

Add environment variable to control JSON Schema output format: - GITLAB_SCHEMA_MODE=flat (default): Flatten discriminated unions to single object with action enum for AI clients compatibility - GITLAB_SCHEMA_MODE=discriminated: Keep oneOf structure with separate branches per action for clients supporting JSON Schema Changes: - Add GITLAB_SCHEMA_MODE and SchemaMode type to config.ts - Update schema-utils.ts to use config import instead of process.env - Rename getSchemaFormat() to getSchemaMode() for consistency - Update tests to mock GITLAB_SCHEMA_MODE Partial implementation of #49

- Fix regex for space replacement to use global flag (/g) - Extract ACTION_DESCRIPTIONS to constant object - Extract action descriptions dynamically from oneOf branches - Update extractParameters to merge params from all oneOf branches - Update generateExample to use first oneOf branch - Add unit tests for getAllToolDefinitionsUnfiltered - Return original schemas in getAllToolDefinitionsUnfiltered for richer docs

- Add 6 tests for GITLAB_SCHEMA_MODE parsing in config.test.ts - Add 6 tests for --export mode in list-tools.test.ts - oneOf schema action extraction - parameter merging with action hints - --toc and --no-examples flags - flat schema fallback

Copilot

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 5 comments.

src/list-tools.ts

src/config.ts

src/list-tools.ts

tests/unit/RegistryManager.test.ts

src/list-tools.ts

- Rename GITLAB_SCHEMA_FORMAT to GITLAB_SCHEMA_MODE throughout - Add documentation for yarn list-tools --export flag - Document --toc and --no-examples options - Describe export mode output: actions table, parameters, examples, tier badges

…tion TOOLS.md export improvements: - Group parameters by common (all actions) vs action-specific - Much cleaner human-readable documentation format - Add extractParametersGrouped() for structured parameter extraction Semantic-release integration: - Auto-generate docs/TOOLS.md during release via @semantic-release/exec - Add TOOLS.md to git assets for automatic commit - Remove manual commit step from CI workflow Code organization: - Move list-tools.ts to src/cli/ directory - Move tests to tests/unit/cli/ PR review fixes: - Add bounds checking for --entity/--tool CLI args - Add clarifying comment for ENTITY_TOOLS categories - Remove unused toolName parameter from generateExample - Add fallback for package.json version detection - Fix misleading test description for getAllToolDefinitionsUnfiltered

Add comprehensive tests for list-tools.ts: - Verbose mode with no parameters - Tier info badges (premium/ultimate/free) - Unresolved $ref type handling - Common + action-specific parameters grouping - Action-specific params sorting by required status - Example generation with all parameter naming patterns

Remove unused oneOf handling from extractParameters function. This code was never executed because extractParametersGrouped handles oneOf schemas directly and only calls extractParameters for flat schemas. Reduces code by ~50 lines and improves coverage to 96%.

Copilot

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.

.github/workflows/ci-cd.yml

src/cli/list-tools.ts

.releaserc.json

Warn users about typos (e.g., --exprt instead of --export) with helpful error message pointing to --help. Also: - Remove unused artifact download from semantic-release CI job - Ensure docs directory exists before TOOLS.md generation

Copilot

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.

## [6.10.0](v6.9.0...v6.10.0) (2026-01-20) ### Features * **docs:** add --export flag to list-tools for TOOLS.md generation ([#51](#51)) ([25f5393](25f5393)), closes [#47](#47) [#49](#49)

Copilot AI review requested due to automatic review settings January 19, 2026 23:25

Copilot started reviewing on behalf of polaz January 19, 2026 23:26 View session

Copilot AI reviewed Jan 19, 2026

View reviewed changes

polaz added 3 commits January 20, 2026 01:31

Merge branch 'main' into feat/47-list-tools-export

7ec7dee

polaz requested a review from Copilot January 19, 2026 23:40

Copilot started reviewing on behalf of polaz January 19, 2026 23:40 View session

Copilot AI reviewed Jan 19, 2026

View reviewed changes

src/list-tools.ts Show resolved Hide resolved

src/config.ts Show resolved Hide resolved

src/list-tools.ts Outdated Show resolved Hide resolved

tests/unit/RegistryManager.test.ts Outdated Show resolved Hide resolved

src/list-tools.ts Show resolved Hide resolved

polaz added 2 commits January 20, 2026 08:05

polaz requested a review from Copilot January 20, 2026 06:43

Copilot started reviewing on behalf of polaz January 20, 2026 06:43 View session

polaz added 2 commits January 20, 2026 08:58

polaz requested review from Copilot and removed request for Copilot January 20, 2026 07:14

Copilot started reviewing on behalf of polaz January 20, 2026 07:14 View session

Copilot AI reviewed Jan 20, 2026

View reviewed changes

.github/workflows/ci-cd.yml Show resolved Hide resolved

src/cli/list-tools.ts Show resolved Hide resolved

.releaserc.json Outdated Show resolved Hide resolved

polaz requested a review from Copilot January 20, 2026 07:21

Copilot started reviewing on behalf of polaz January 20, 2026 07:22 View session

fix(cli): add error handling for unrecognized flags

5b32648

Warn users about typos (e.g., --exprt instead of --export) with helpful error message pointing to --help. Also: - Remove unused artifact download from semantic-release CI job - Ensure docs directory exists before TOOLS.md generation

polaz force-pushed the feat/47-list-tools-export branch from db4ccc7 to 5b32648 Compare January 20, 2026 07:23

Copilot AI reviewed Jan 20, 2026

View reviewed changes

polaz merged commit 25f5393 into main Jan 20, 2026
12 checks passed

polaz deleted the feat/47-list-tools-export branch January 20, 2026 07:24

sw-release-bot bot mentioned this pull request Mar 29, 2026

chore(main): release gitlab-mcp 7.0.0 #368

Open

Conversation

polaz commented Jan 19, 2026

Summary

Usage

Example Output

Test plan

Uh oh!

github-actions bot commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📊 Test Coverage Report

Coverage Details

Uh oh!

codecov bot commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

github-actions bot commented Jan 19, 2026 •

edited

Loading

codecov bot commented Jan 19, 2026 •

edited

Loading