Move JSDoc examples to type-checked .examples.ts files#302
Merged
jonathanhefner merged 3 commits intomodelcontextprotocol:mainfrom Jan 20, 2026
Merged
Move JSDoc examples to type-checked .examples.ts files#302jonathanhefner merged 3 commits intomodelcontextprotocol:mainfrom
.examples.ts files#302jonathanhefner merged 3 commits intomodelcontextprotocol:mainfrom
Conversation
@modelcontextprotocol/ext-apps
@modelcontextprotocol/server-basic-react
@modelcontextprotocol/server-basic-vanillajs
@modelcontextprotocol/server-budget-allocator
@modelcontextprotocol/server-cohort-heatmap
@modelcontextprotocol/server-customer-segmentation
@modelcontextprotocol/server-map
@modelcontextprotocol/server-pdf
@modelcontextprotocol/server-scenario-modeler
@modelcontextprotocol/server-shadertoy
@modelcontextprotocol/server-sheet-music
@modelcontextprotocol/server-system-monitor
@modelcontextprotocol/server-threejs
@modelcontextprotocol/server-transcript
@modelcontextprotocol/server-video-resource
@modelcontextprotocol/server-wiki-explorer
commit: |
ochafik
reviewed
Jan 19, 2026
| * | ||
| * await bridge.connect(transport); | ||
| * ``` | ||
| * {@includeCode ./app-bridge.examples.ts#AppBridge_basicUsage} |
Contributor
There was a problem hiding this comment.
This means people opening the sources may struggle to see examples. Could we have an opposite system similar to the snippet-source in the Python SDK? (leave snippets in place w/ markers that allow extracting them and testing them )
Member
Author
There was a problem hiding this comment.
@includeCode is integrated into TypeDoc (it is a feature of TypeDoc).
Could you explain more about Nevermind, I see how it works.snippet-source? How does it allow type-checked examples?
I can look into something like that, but we would need to use custom TypeDoc tags for start and end delimiters; otherwise, TypeDoc will render those (there is no equivalent to <!-- --> inside a JSDoc comment). That said, I would prefer to merge this as is, because I am using some of these .example.ts files in the doc/patterns.md document I am working on.
Contributor
There was a problem hiding this comment.
Also, JSDoc should simply ignore any @tag it doesn't recognize. So you can use arbitrary custom tags and JSDoc won't error or do anything with them:
/**
* @startSnippet path
* ...
* @endSnippet
*/
function foo() { ... }
Member
Author
There was a problem hiding this comment.
Hmm, not exactly. TypeDoc does output a warning instead of an error for unknown tags, but they still affect the output.
I tried with both block tags (e.g., * @startSnippet ./app-bridge.examples.ts#AppBridge_basicUsage) and inline tags (e.g., * {@startSnippet ./app-bridge.examples.ts#AppBridge_basicUsage}):
| Block | Inline |
|---|---|
 |
 |
Relative directory links like `](examples/map-server)` caused TypeDoc
warnings ("relative path is not a file") and resulted in broken links
in the generated API documentation. Converted all 20 example directory
links to full GitHub URLs while keeping image paths relative.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Extract inline code examples from JSDoc comments into companion
`.examples.ts`/`.examples.tsx` files. Examples are now:
- Type-checked by wrapping them in functions
- Referenced via `{@includecode ./file.examples.ts#regionName}` tags
- Organized using `//#region` and `//#endregion` markers
This keeps the main source files cleaner while ensuring examples
compile correctly. Updated TypeDoc config with `exampleTag: false`
to support title text on `@example` tags.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Follow-up to the examples extraction: pass dependencies as function parameters instead of using global stub declarations, rename region names to match method names (e.g., `AppBridge_guestCapabilities_*` → `AppBridge_getAppCapabilities_*`), and simplify examples using optional chaining. Also clarifies `RESOURCE_URI_META_KEY` documentation to indicate it's for tool definition metadata (from `tools/list`), not tool result metadata, and removes the redundant `setNotificationHandler` example in favor of the simpler event setter approach. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
jonathanhefner
force-pushed
the
checked-examples
branch
from
a88cf45 to
f0c7cc1
Compare
Merged
ochafik
approved these changes
Jan 20, 2026
jonathanhefner
merged commit 26ae13d
into
modelcontextprotocol:main
13 of 14 checks passed
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.
Extract inline code examples from JSDoc comments into companion
.examples.ts/.examples.tsxfiles. Examples are now:{@includecode ./file.examples.ts#regionName}tags//#regionand//#endregionmarkersThis keeps the main source files cleaner while ensuring examples compile correctly. Updated TypeDoc config with
exampleTag: falseto support title text on@exampletags.Co-Authored-By: Claude Opus 4.5 noreply@anthropic.com