Adds a full MkDocs Material documentation site deployed to GitHub Pages via GitHub Actions, plus an auto-generated tool reference.#499
Conversation
- Set up MkDocs Material documentation site, deployed to GitHub Pages
via a new .github/workflows/docs.yml (build with --strict, deploy via
actions/deploy-pages on push to main).
- Reorganize the 14 existing docs/*.md guides into a structured nav:
clients/ Claude Code, VS Code, Copilot, Cursor, Codex, JSON clients
auth/ OAuth setup, OAuth callback proxy, custom-agent multi-PAT
configuration/ Environment variables, dynamic API URL, stateless mode
features/ Resolve issue thread
reference/ GitHub secrets setup, dependency proxy design
All moves use git mv so per-file history is preserved; internal
cross-links between guides are rewritten to the new paths.
- Add new hand-written pages: docs/index.md (home), docs/getting-started/
(auth-method comparison + CLI arguments reference), and a Contributing
page mirrored from the new root CONTRIBUTING.md.
- Auto-generate the Tools Reference: a new scripts/generate-tool-docs.ts
imports allTools and TOOLSET_DEFINITIONS from tools/registry.ts and
emits one page per tool group under docs/tools/. Each page lists every
tool with its description and a parameter table derived from the
authoritative Zod schemas in schemas.ts. 196 tools documented across
20 group pages + an overview index.
- Add a Makefile with make serve (preview), make build (strict CI
build), make tools-docs (regenerate the reference), and make clean.
Pin docs deps in requirements-docs.txt.
- Add CONTRIBUTING.md at the repo root (GitHub convention) covering dev
setup, project layout, the new-tool checklist, testing, code style,
PR flow, and docs contribution.
- Update README.md: repoint the 17 ./docs/* links to the new subfolder
paths and add a documentation banner pointing at the hosted site.
- Update .gitignore to exclude site/ (MkDocs output) and .venv-docs/.
docs: add GitHub Pages site with auto-generated tool reference
|
Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
https://github.com/zereight/gitlab-mcp/blob/31405d66f61c93fbcb647ab7b853165ea881b6f5/docs/claude-code-setup.md#L1
Removing the old top-level docs paths without redirects leaves the localized READMEs pointing at files that no longer exist; rg "docs/(claude-code-setup|vscode-setup|oauth-setup|environment-variables)\.md" README*.md still finds many references in README.ko.md and README.zh-CN.md, so users following those setup guides now hit 404s. Please either update the localized README links alongside the English README or keep stub redirect pages for the moved guides.
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
The English README was updated to the reorganized docs/ subfolder
paths, but README.ko.md and README.zh-CN.md were missed and still
pointed at the old top-level filenames (./docs/claude-code-setup.md,
./docs/oauth-setup.md, ./docs/environment-variables.md, etc.),
producing 404s for Korean and Chinese readers.
Repoint all 9 link patterns in both files to match the English README:
./docs/clients/<client>.md
./docs/auth/oauth-setup.md, ./docs/auth/oauth-callback-proxy.md
./docs/configuration/{environment-variables,dynamic-api-url}.md
Reported by chatgpt-codex-connector on the PR.
docs: update localized README links to new doc paths
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9621c016d9
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
…IONS
The hand-written "Feature toggles" table in the Tools overview wrongly
listed Work Items, Releases, Tags, Variables, Webhooks, Search, and
Dependency Proxy as part of the always-on core. In reality those
toolsets are marked `isDefault: false` in `TOOLSET_DEFINITIONS` and
must be opted into via `GITLAB_TOOLSETS`, `GITLAB_TOOLS`, or the
runtime `discover_tools` MCP tool. The legacy `USE_PIPELINE` /
`USE_MILESTONE` / `USE_GITLAB_WIKI` flags only cover those three
specific groups for backward compatibility.
Refactor scripts/generate-tool-docs.ts so the table is derived from
the source of truth instead of hand-curated:
- Add `LEGACY_TOGGLE_ENV` mapping pipelines/milestones/wiki → their
legacy env flag names.
- Add `isDefaultToolset(id)` and `computeToggleNote(id)` helpers.
computeToggleNote() returns:
* undefined for default-on groups,
* a GITLAB_TOOLSETS + legacy-flag note for pipelines/milestones/wiki,
* a GITLAB_TOOLSETS / GITLAB_TOOLS / discover_tools note for the
other opt-in groups,
* a special note for the synthetic "Meta & GraphQL" group explaining
that `discover_tools` is always exposed but `execute_graphql` is
opt-in via GITLAB_TOOLS.
- Remove the hand-written `toggleNote` fields from GROUP_META; the
helper replaces them.
- New `buildToggleSection()` produces a two-row Default / Opt-in table
with all group titles linked to their per-group pages.
- Per-group pages and the overview per-group rows both call
computeToggleNote() so the wording stays consistent.
Also add `docs/tools/*.md`, `site/`, and `.venv-docs/` to
`.prettierignore` — those files are owned by the generator (or the
MkDocs build), and letting Prettier rewrite them creates a churn loop
on the next `make tools-docs`.
Verified:
- `make tools-docs` is idempotent (two consecutive runs diff to 0)
- mkdocs build --strict passes (40 pages, 0 warnings)
- 196 tools documented, perfect 1:1 with TOOLSET_DEFINITIONS source
- npx tsc --noEmit clean
Addresses chatgpt-codex-connector review on PR zereight#499.
docs(tools): derive default/opt-in toolset table from TOOLSET_DEFINITIONS
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 1bab93556f
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
The generator's classify() used name-prefix heuristics + a small "exact match" exception list to label tools as 📖 Read-only or ✏️ Writes. That works for ~95% of tools but quietly misclassifies anything that doesn't follow a list_/get_/search_/etc. pattern. Concrete bug: `execute_graphql` was labeled ✏️ Writes on docs/tools/meta.md even though the server's own `readOnlyTools` set (tools/registry.ts:1233) includes it — meaning read-only mode actually keeps it available. The docs made read-only deployments look less capable than they really are. Replace the heuristics with a single import of the authoritative `readOnlyTools` set from tools/registry.ts. classify() is now a one-line `readOnlyTools.has(name) ? "read" : "write"`. This matches the server's own GITLAB_READ_ONLY_MODE filter exactly, and any future tool added to the registry will be classified correctly without touching this script. Drops the now-unused READ_PREFIXES array and READ_EXACT set. Regenerated docs/tools/: only execute_graphql's badge actually flipped (everything else was already correctly classified by the heuristic). Both consecutive `make tools-docs` runs are byte-identical; mkdocs build --strict passes; 196/196 tools documented. Addresses chatgpt-codex-connector review on PR zereight#499.
docs(tools): drive R/W badge from authoritative readOnlyTools set
|
@codex review |
|
Codex Review: Didn't find any major issues. Nice work! ℹ️ About Codex in GitHubCodex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback". |
|
@zereight, could you please review the PR? I have added a complete MkDocs Material documentation site that is deployed to GitHub Pages via GitHub Actions, along with an auto-generated tool reference. |
1 participant
Adds a full MkDocs Material documentation site deployed to GitHub Pages via GitHub Actions, plus an auto-generated tool reference.
docs/*.mdguides reorganised into structured nav (clients/,auth/,configuration/,features/,reference/) — all moves usegit mvso per-file history is preservedtools/registry.ts+ Zod schemas inschemas.tsviascripts/generate-tool-docs.tsMakefile(make serve/make build/make tools-docs/make clean) and pinnedrequirements-docs.txtCONTRIBUTING.mdat repo root + mirrored docs page.gitignoreexcludessite/and.venv-docs/How tools docs stay in sync
The per-group pages under
docs/tools/are produced byscripts/generate-tool-docs.ts, which:allTools+TOOLSET_DEFINITIONSfromtools/registry.tsinputSchema(zodToJsonSchema(...)). Re-runmake tools-docsafter adding/renaming a tool. See the new Contributing → "When changing tools, schemas, or toolsets" section.Deploy details
.github/workflows/docs.yml: builds withmkdocs build --strict, deploys viaactions/deploy-pages@v4. Only runs on push tomainwhendocs/,mkdocs.yml, orrequirements-docs.txtchange (plusworkflow_dispatch).mkdocs.ymlsite_urlis set tohttps://zereight.github.io/gitlab-mcp/. After the merge, enabling Pages on this repo (Settings → Pages → Source: GitHub Actions) is the only one-time setup needed.Test plan
mkdocs build --strictpasses locally (0 warnings, 40 pages, ~0.9s).mdlinks across docs resolvemkdocs.ymlnav targets existtools/registry.tsdocumented (1:1 match)make tools-docstwice produces no diffnpx tsc --noEmitclean (script type-checks under project config)zereight/gitlab-mcp(Settings → Pages → Source: GitHub Actions) before/after merge.