docs: Critical documentation refactor - VitePress site with MCP install badges by polaz · Pull Request #133 · structured-world/gitlab-mcp

polaz · 2026-01-22T22:35:12Z

Summary

Migrate README (1125 lines) to VitePress static site (129 lines + 15 doc pages)
Fix outdated tool count: 62 → 47 (post-CQRS consolidation)
Add MCP one-click install badges (VS Code, VS Code Insiders)
Unified GitHub Pages deployment with coverage integration on release

Changes

VitePress Documentation Site

docs/.vitepress/config.mts — Site config with nav, sidebar, search
docs/index.md — Home page with hero, features, install badges
docs/guide/ — Introduction, Quick Start, Installation (npm, Docker, VS Code, Codex), Configuration, Auto-Discovery, Transport
docs/security/ — OAuth Authentication, Read-Only Mode
docs/advanced/ — TLS/HTTPS, Customization (descriptions, action filtering, schema mode)
docs/tools/ — Tool Reference (47 tools, correct count)
docs/cli/ — list-tools CLI documentation

CI/CD

.github/workflows/docs.yml — VitePress build + deploy on docs changes and releases; coverage integrated on release only
.github/workflows/coverage-pages.yml — Refactored to PR-only (coverage comments)

Other

CONTRIBUTING.md — Dev setup, testing, architecture, PR guidelines
README.md — Reduced to minimal with links to docs site
package.json — Added docs:dev, docs:build, docs:preview scripts
.gitignore — VitePress dist/cache

Test plan

yarn lint — 0 errors
yarn test — 3478 tests passed
yarn build — successful
yarn docs:build — VitePress builds in ~2s
Verify docs deploy on merge to main
Verify coverage integration on next release

Closes #24

…#24) - Add VitePress with docs:dev/build/preview scripts - Create full documentation site: guide, security, advanced, cli, tools - Migrate all README sections to dedicated pages - Add GitHub Actions workflow for docs deployment to Pages - Add MCP one-click install badges (VS Code, VS Code Insiders) - Create CONTRIBUTING.md with dev setup, testing, and PR guidelines - Reduce README from 1125 to 129 lines (links to docs site) - Fix outdated tool count: 62 → 47 (post-CQRS consolidation) - Remove outdated per-tool listings (replaced by auto-generated TOOLS.md)

github-actions · 2026-01-22T22:36:27Z

Test Coverage Report

Overall Coverage: 91.92%

Metric	Percentage
Statements	91.51%
Branches	83.43%
Functions	81.07%
Lines	91.92%

View detailed coverage report

codecov · 2026-01-22T22:37:24Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

Remove duplicate author attribution, streamline README structure, and fix VS Code one-click install deeplinks to use correct URL-encoded JSON format.

Copilot

Pull request overview

Migrates the project documentation from a large README into a VitePress site, adds MCP one-click install badges, and updates CI workflows to deploy docs (and publish coverage into the docs site on releases).

Changes:

Introduced a VitePress documentation site under docs/ with guides, security docs, advanced configuration, and a tool reference.
Added VitePress scripts/dependency and updated .gitignore for VitePress build artifacts.
Refactored GitHub Actions: new docs deploy workflow, and simplified coverage workflow to PR-only commenting.

Reviewed changes

Copilot reviewed 22 out of 24 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
yarn.lock	Adds VitePress (and transitive deps) lockfile entries.
package.json	Adds `vitepress` devDependency and `docs:*` scripts.
docs/.vitepress/config.mts	New VitePress config (nav/sidebar/search/edit links).
docs/index.md	New docs homepage with hero and MCP install badges.
docs/guide/index.md	Introduction and feature overview moved to docs.
docs/guide/quick-start.md	Quick start guide for configuring MCP clients.
docs/guide/installation/npm.md	npm/npx and yarn dlx installation docs.
docs/guide/installation/docker.md	Docker installation docs for stdio + HTTP modes.
docs/guide/installation/vscode.md	VS Code setup + one-click install instructions.
docs/guide/installation/codex.md	Codex configuration instructions.
docs/guide/configuration.md	Environment variable reference moved to docs.
docs/guide/auto-discovery.md	Auto-discovery documentation added.
docs/guide/transport.md	Transport mode selection docs added.
docs/security/oauth.md	OAuth setup + endpoints + troubleshooting docs added.
docs/security/read-only.md	Read-only mode behavior docs added.
docs/advanced/tls.md	TLS / reverse-proxy deployment docs added.
docs/advanced/customization.md	Action filtering/description override/schema mode docs added.
docs/tools/index.md	Tool reference overview updated to 47 tools.
docs/cli/list-tools.md	`list-tools` CLI usage and doc generation instructions added.
README.md	Reduced README with links to docs and install badges.
CONTRIBUTING.md	Added contribution guide covering setup/testing/standards.
.gitignore	Ignores VitePress dist/cache outputs.
.github/workflows/docs.yml	New docs build/deploy workflow; integrates coverage on releases only.
.github/workflows/coverage-pages.yml	Refactored to PR-only coverage run + PR comment.

docs/.vitepress/config.mts

docs/guide/auto-discovery.md

README.md

docs/.vitepress/config.mts

…r---fix-22-miss

Copilot

Pull request overview

Copilot reviewed 22 out of 24 changed files in this pull request and generated 4 comments.

.github/workflows/coverage-pages.yml

docs/.vitepress/config.mts

docs/security/read-only.md

Copilot

Pull request overview

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

docs/tools/index.md

docs/security/oauth.md

.github/workflows/docs.yml

The docs deploy workflow uses `yarn install --immutable` which depends on yarn.lock. Include it in path filters so lockfile changes trigger a rebuild.

Copilot

Pull request overview

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

docs/security/read-only.md

README.md

docs/tools/index.md

docs/guide/quick-start.md

docs/guide/configuration.md

docs/tools/index.md

- Note manage_context exception in read-only mode docs - Add 'opt-in' label to disabled-by-default feature flags - Add section header explaining opt-in groups reduce tool count

Copilot

Pull request overview

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

docs/tools/index.md

docs/security/oauth.md

package.json

README.md

docs/guide/quick-start.md

- All feature flags default to true (code uses !== "false" pattern) - Add /register (Dynamic Client Registration) to OAuth endpoints - Set DOCS_BASE=/ in local VitePress scripts for correct local preview

Copilot

Pull request overview

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

docs/guide/installation/npm.md

docs/guide/installation/docker.md

docs/tools/index.md

…r---fix-22-miss

- Add USE_RELEASES, USE_REFS, USE_MEMBERS, USE_SEARCH to all docs - Move gated tools out of "Core (Always Available)" into own sections - Fix Docker example to forward all USE_* flags - Fix npm example with all 15 feature flags

Copilot

Pull request overview

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

sw-release-bot · 2026-01-23T15:26:36Z

🎉 This PR is included in version 6.31.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

polaz added 3 commits January 23, 2026 00:16

ci(docs): unified Pages deployment with release trigger

dfc56c2

ci(docs): conditional coverage on release only

9bd9f04

Copilot AI review requested due to automatic review settings January 22, 2026 22:35

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

docs: clean up README and fix MCP install badge URLs

195d2e8

Remove duplicate author attribution, streamline README structure, and fix VS Code one-click install deeplinks to use correct URL-encoded JSON format.

Copilot AI reviewed Jan 22, 2026

View reviewed changes

docs/.vitepress/config.mts Outdated Show resolved Hide resolved

docs/guide/auto-discovery.md Outdated Show resolved Hide resolved

README.md Outdated Show resolved Hide resolved

docs/.vitepress/config.mts Outdated Show resolved Hide resolved

polaz added 2 commits January 23, 2026 00:51

docs(config): configurable base path and canonical domain links

7618f35

Merge branch 'main' into feat/#24-docs-critical-documentation-refacto…

4b32ff1

…r---fix-22-miss

polaz requested a review from Copilot January 22, 2026 22:52

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

Copilot AI reviewed Jan 22, 2026

View reviewed changes

.github/workflows/coverage-pages.yml Show resolved Hide resolved

docs/.vitepress/config.mts Show resolved Hide resolved

docs/security/read-only.md Show resolved Hide resolved

docs/security/read-only.md Show resolved Hide resolved

polaz mentioned this pull request Jan 23, 2026

refactor(read-only): move read-only actions from manage_* to browse_* tools #134

Closed

ci(docs): set DOCS_BASE=/ for custom domain, add continue-on-error

b4adc2e

polaz requested a review from Copilot January 23, 2026 08:07

Copilot started reviewing on behalf of polaz January 23, 2026 08:07 View session

Copilot AI reviewed Jan 23, 2026

View reviewed changes

docs/tools/index.md Show resolved Hide resolved

docs/security/oauth.md Show resolved Hide resolved

.github/workflows/docs.yml Show resolved Hide resolved

ci(docs): add yarn.lock to workflow path triggers

55d51f3

The docs deploy workflow uses `yarn install --immutable` which depends on yarn.lock. Include it in path filters so lockfile changes trigger a rebuild.

polaz requested a review from Copilot January 23, 2026 10:15

Copilot started reviewing on behalf of polaz January 23, 2026 10:16 View session

Copilot AI reviewed Jan 23, 2026

View reviewed changes

docs: clarify opt-in tool groups and read-only exceptions

4a65d08

- Note manage_context exception in read-only mode docs - Add 'opt-in' label to disabled-by-default feature flags - Add section header explaining opt-in groups reduce tool count

polaz requested a review from Copilot January 23, 2026 11:12

Copilot started reviewing on behalf of polaz January 23, 2026 11:12 View session

Copilot AI reviewed Jan 23, 2026

View reviewed changes

docs/tools/index.md Outdated Show resolved Hide resolved

docs/security/oauth.md Show resolved Hide resolved

package.json Outdated Show resolved Hide resolved

README.md Outdated Show resolved Hide resolved

docs/guide/quick-start.md Outdated Show resolved Hide resolved

docs: fix feature flag defaults, add /register endpoint, set DOCS_BASE

2b40795

- All feature flags default to true (code uses !== "false" pattern) - Add /register (Dynamic Client Registration) to OAuth endpoints - Set DOCS_BASE=/ in local VitePress scripts for correct local preview

polaz requested a review from Copilot January 23, 2026 14:00

Copilot started reviewing on behalf of polaz January 23, 2026 14:00 View session

Copilot AI reviewed Jan 23, 2026

View reviewed changes

docs/guide/installation/npm.md Show resolved Hide resolved

docs/guide/installation/docker.md Show resolved Hide resolved

docs/tools/index.md Show resolved Hide resolved

polaz added 2 commits January 23, 2026 16:11

Merge branch 'main' into feat/#24-docs-critical-documentation-refacto…

ed63303

…r---fix-22-miss

Merge branch 'main' into feat/#24-docs-critical-documentation-refacto…

40483f8

…r---fix-22-miss

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

Copilot started reviewing on behalf of polaz January 23, 2026 14:22 View session

Copilot AI reviewed Jan 23, 2026

View reviewed changes

polaz merged commit d1d5487 into main Jan 23, 2026
19 checks passed

polaz deleted the feat/#24-docs-critical-documentation-refactor---fix-22-miss branch January 23, 2026 14:31

sw-release-bot bot added the released label Jan 23, 2026

Conversation

polaz commented Jan 22, 2026

Summary

Changes

VitePress Documentation Site

CI/CD

Other

Test plan

Uh oh!

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

Uh oh!

Test Coverage Report

Uh oh!

codecov bot commented Jan 22, 2026

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!

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!

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!

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!

sw-release-bot bot commented Jan 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

github-actions bot commented Jan 22, 2026 •

edited

Loading