Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

feat: generate Layer-1 MCP tool docs from toolRegistry / Zod schemas

Open
  • Is something wrong?
#984 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
json, markdown, typescript
Domain
api, documentation, tooling

Research direction

Start from the @tool registrations in src/api and the registry path used by e2e/scripts/generate-mcp-types.ts, then check how src/mcp/mcp.middleware.ts converts Zod schemas with zodToJsonSchema. Decide the output layout (checked-in docs/api/mcp/ versus CI artifact) with maintainers first. Done means npm run generate:mcp-docs emits an index and per-tool pages covering every registered tool, and CI flags stale output.

Written by the indexing model from the issue text.

Description

Summary

Cocos CLI exposes a large MCP tool surface (@tool + Zod in src/api), but there is no machine-generated API/tool documentation. Humans and agents currently have to reverse-engineer schemas from source (and some critical fields like OpenPaaS accessToken are easy to miss because they are optional / not on a dedicated openpaas branch).

We previously mapped the CLI into four layers:

  1. Tools (MCP) — src/api @tool registry → what agents actually call
  2. Commands — src/commands / CLI entry
  3. Lib facade — src/lib
  4. Core — src/core (+ scene-process RPC)

This issue is specifically about Layer 1: ship a documentation generator (not a one-off markdown dump) that keeps docs in sync with code.

Motivation

  • Existing docs/ is hand-written Markdown only — no TypeDoc / API site pipeline.
  • We already reverse-generate types/schemas for machines (generate:mcp-types, zodToJsonSchema in McpMiddleware, generate:dts, typescript-json-schema), but nothing produces human-readable tool docs from the same source of truth.
  • PinK / agent users hit gaps such as: OpenPaaS build requiring packages.*.accessToken while schema marks it optional and platform=openpaas falls into the catch-all option branch.

Proposal

Add a maintainable generator, e.g.:

  • Script: workflow/generate-mcp-tool-docs.ts (or under e2e/scripts/)
  • npm script: generate:mcp-docs
  • Input: runtime toolRegistry (same path as generate:mcp-types) + Zod → JSON Schema (zodToJsonSchema, Gemini-flat style preferred)
  • Output (checked in or CI artifact):
    • docs/api/mcp/README.md — index by category + tool count
    • docs/api/mcp/<category>/<tool>.md — title, description, params, result schema, source file pointer
    • optional docs/api/mcp/tools.json for tooling

Phase 2 (out of scope for first PR, but leave hooks): generate docs for Commands / Lib / Core layers the same way.

Acceptance criteria

  • npm run generate:mcp-docs regenerates Layer-1 docs from current @tool registrations
  • CI fails (or warns) if generated docs are stale vs source
  • Every registered tool has name / title / description / inputSchema / outputSchema documented
  • Generated docs call out platform-specific packages.* fields (including OpenPaaS-related optional fields)
  • CONTRIBUTING.md documents when to run the generator

Related existing machinery

  • e2e/scripts/generate-mcp-types.ts — registry → TS types
  • src/mcp/mcp.middleware.ts — zodToJsonSchema for tools/list
  • workflow/generate-dts.ts / workflow/generate-schema.js — types/config schema only, not docs

Non-goals (for this issue)

  • Full TypeDoc website for all of src/core
  • Changing MCP runtime behavior
  • Hand-writing the entire tool catalog once without a regenerator
Dominant language
TypeScript
Stars
450
Forks
158
Avg merge
3d 4h
Merged PRs (30d)
33

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from cocos/cocos-cli

All issues in cocos/cocos-cli

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.