Generate schema reference page based on template (modelcontextprotocol#1085)

* Hide `@TJS-type` tag artifacts in `schema.mdx`

Previously, `@TJS-type` tags were not recognized by TypeDoc because of
the hyphen in their name.  However, [TypeDoc v0.28.8][] supports such
tags, allowing them to be listed in the `excludeTags` option.

This commit upgrades TypeDoc to the latest version, and adds `@TJS-type`
tags to the `excludeTags` configuration option, preventing their
appearance in `schema.mdx`.

[TypeDoc v0.28.8]: https://github.com/TypeStrong/typedoc/releases/tag/v0.28.8

* Prioritize RPC-related types in schema reference

This changes the order of the schema reference page such that
RPC-related types are listed first and common types are listed last.
This also adds logic to ensure that, for a given RPC method, the
relevant types are ordered as follows: `*Request` type, `*RequestParams`
type, `*Result` type, `*Notification` type, `*NotificationParams` type,
and then any other relevant types in alphabetical order.

* Categorize more types in `schema.ts`

This adds `@category` tags to more types in `schema.ts`.  (The schema
reference page uses these categories to organize types.)

* Generate schema reference page based on template

This commit modifies the TypeDoc plugin to generate the schema reference
page based on a template `schema.mdx` file instead of based solely on
the content of `schema.ts`.  The template file uses placeholders to
indicate where categories of types should be rendered.  For example, the
``{/* @category `tools/call` */}`` placeholder will be replaced by the
documentation for all types in the `` `tools/call` `` category.

This change gives us more control over headings and category order, and
allows us to easily add surrounding prose.

Author: jonathanhefner

docs/specification/2025-06-18/schema.mdx

@@ -25,13 +25,13 @@
     "check:schema": "npm run check:schema:ts && npm run check:schema:json && npm run check:schema:md",
     "check:schema:ts": "tsc --noEmit && eslint schema/ && prettier --check \"schema/**/*.ts\"",
     "check:schema:json": "for f in schema/*/schema.ts; do typescript-json-schema --defaultNumberType integer --required --skipLibCheck \"$f\" \"*\" | cat | cmp \"${f%.ts}.json\" - || exit 1; done",
-    "check:schema:md": "for f in docs/specification/*/schema.mdx; do typedoc --entryPoints \"schema/$(basename -- $(dirname -- \"$f\"))/schema.ts\" | cmp \"$f\" - || exit 1; done",
+    "check:schema:md": "for f in schema/*/schema.mdx; do typedoc --entryPoints \"${f%.mdx}.ts\" --schemaPageTemplate \"$f\" | cmp docs/specification/$(basename -- $(dirname -- \"$f\"))/schema.mdx - || exit 1; done",
     "check:docs": "npm run check:docs:format && npm run check:docs:links",
     "check:docs:format": "prettier --check \"**/*.{md,mdx}\"",
     "check:docs:links": "cd docs && npx mint broken-links",
     "generate:schema": "npm run generate:schema:json && npm run generate:schema:md",
     "generate:schema:json": "for f in schema/*/schema.ts; do typescript-json-schema --defaultNumberType integer --required --skipLibCheck \"$f\" \"*\" -o \"${f%.ts}.json\"; done",
-    "generate:schema:md": "for f in docs/specification/*/schema.mdx; do typedoc --entryPoints \"schema/$(basename -- $(dirname -- \"$f\"))/schema.ts\" > \"$f\"; done",
+    "generate:schema:md": "for f in schema/*/schema.mdx; do typedoc --entryPoints \"${f%.mdx}.ts\" --schemaPageTemplate \"$f\" > docs/specification/$(basename -- $(dirname -- \"$f\"))/schema.mdx; done",
     "format": "prettier --write \"**/*.{md,mdx}\" --ignore \"docs/specification/*/schema.mdx\" ",
     "serve:docs": "cd docs && npx mint dev",
     "serve:blog": "cd blog && hugo serve"
@@ -45,7 +45,7 @@
     "glob": "^11.0.0",
     "prettier": "^3.6.2",
     "tsx": "^4.19.1",
-    "typedoc": "^0.28.7",
+    "typedoc": "^0.28.14",
     "typescript": "^5.6.2",
     "typescript-eslint": "^8.0.0",
     "typescript-json-schema": "^0.65.1"

docs/specification/draft/schema.mdx

@@ -0,0 +1,117 @@
+---
+title: Schema Reference
+---
+
+<div id="schema-reference" />
+
+## JSON-RPC
+
+{/* @category JSON-RPC */}
+
+## Common Types
+
+{/* @category Common Types */}
+
+## Content
+
+{/* @category Content */}
+
+## `completion/complete`
+
+{/* @category `completion/complete` */}
+
+## `elicitation/create`
+
+{/* @category `elicitation/create` */}
+
+## `initialize`
+
+{/* @category `initialize` */}
+
+## `logging/setLevel`
+
+{/* @category `logging/setLevel` */}
+
+## `notifications/cancelled`
+
+{/* @category `notifications/cancelled` */}
+
+## `notifications/initialized`
+
+{/* @category `notifications/initialized` */}
+
+## `notifications/message`
+
+{/* @category `notifications/message` */}
+
+## `notifications/progress`
+
+{/* @category `notifications/progress` */}
+
+## `notifications/prompts/list_changed`
+
+{/* @category `notifications/prompts/list_changed` */}
+
+## `notifications/resources/list_changed`
+
+{/* @category `notifications/resources/list_changed` */}
+
+## `notifications/resources/updated`
+
+{/* @category `notifications/resources/updated` */}
+
+## `notifications/roots/list_changed`
+
+{/* @category `notifications/roots/list_changed` */}
+
+## `notifications/tools/list_changed`
+
+{/* @category `notifications/tools/list_changed` */}
+
+## `ping`
+
+{/* @category `ping` */}
+
+## `prompts/get`
+
+{/* @category `prompts/get` */}
+
+## `prompts/list`
+
+{/* @category `prompts/list` */}
+
+## `resources/list`
+
+{/* @category `resources/list` */}
+
+## `resources/read`
+
+{/* @category `resources/read` */}
+
+## `resources/subscribe`
+
+{/* @category `resources/subscribe` */}
+
+## `resources/templates/list`
+
+{/* @category `resources/templates/list` */}
+
+## `resources/unsubscribe`
+
+{/* @category `resources/unsubscribe` */}
+
+## `roots/list`
+
+{/* @category `roots/list` */}
+
+## `sampling/createMessage`
+
+{/* @category `sampling/createMessage` */}
+
+## `tools/call`
+
+{/* @category `tools/call` */}
+
+## `tools/list`
+
+{/* @category `tools/list` */}