Add generated tool reference doc with CI guard - #407
Merged
Conversation
Add `cmd/docs-gen`, a generator that reflects over the registered MCP toolsets and emits `docs/tool-reference.md` — a per-toolset CRUD matrix covering all four products (Projects, Desk, Spaces, Chat). It requires no token or live server; only static tool metadata is read. The doc mirrors what shipped servers actually expose: groups are built with allowDelete=false, so delete operations (which exist in code but are gated off in every shipped server) are intentionally omitted rather than shown as available. Guard tests ride the existing `go test ./...` CI: - golden check (doc matches generator output) - bijection (every tool renders exactly once, nothing silently dropped) - annotation cross-check (Get/List => ReadOnlyHint, Create/Update => not) - no-delete guard, plus a gated-existence counterpart A `-check` flag verifies the committed doc locally. AGENTS.md documents the two changes CI cannot auto-detect (flipping allowDelete on a shipped server, or adding a new product package). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds
cmd/docs-gen, a generator that reflects over the registered MCP toolsets and emitsdocs/tool-reference.md— a per-toolset CRUD matrix covering all four products (Projects, Desk, Spaces, Chat). No token or live server needed; it reads only static tool metadata (nilengine/HTTP client), so it's hermetic.The tool reference is now linked from the README.
Accuracy: deletes are intentionally omitted
Delete tools exist in the codebase but are gated behind
allowDelete, which no shipped server enables (cmd/mcp-httpandcmd/mcp-stdioboth passfalse, and there's no flag/env to flip it). Showing deletes as available would mislead readers, so the generator builds groups withallowDelete=falseto mirror exactly what a client receives. The header note explains this.Self-policing in CI
Guard tests ride the existing
go test ./...workflow (no new Actions file):ReadOnlyHint=true, Create/Update must befalse(catches a mis-verb-named tool in the wrong column).A
-checkflag verifies the committed doc locally:go run ./cmd/docs-gen -check.Known manual triggers (documented in AGENTS.md)
A golden check enforces "doc matches generator," not "doc matches reality." Two changes CI cannot auto-detect, now called out in AGENTS.md:
allowDeletetotrueon a shipped server.products()).Test plan
gofmt -l,go vet ./cmd/docs-gen,go build ./...— cleango test ./cmd/docs-gen— all 5 guards passgo run ./cmd/docs-gen -check— exits 0 (doc current)🤖 Generated with Claude Code