Replace {@includeCode} with synced code fences
Migrate JSDoc and markdown documentation from `{@includeCode ./file#region}`
tags to inline code fences with `source="./file#region"` attributes.
Code examples are now visible directly in source files while remaining
type-checked via their `.examples.ts` source files.
Add `scripts/sync-snippets.ts` to extract code from `//#region` blocks
and sync it into labeled fences. Run with `npm run sync:snippets`.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Jonathan Hefner
parent
ac65f46026
commit
58019a48ce
1 changed files with 1776 additions and 96 deletions
|
|
@ -8,7 +8,27 @@
|
|||
* @module server-helpers
|
||||
*
|
||||
* @example
|
||||
* {@includeCode ./index.examples.ts#index_overview}
|
||||
* ```ts source="./index.examples.ts#index_overview"
|
||||
* // Register a tool that displays a view
|
||||
* registerAppTool(
|
||||
* server,
|
||||
* "weather",
|
||||
* {
|
||||
* description: "Get weather forecast",
|
||||
* _meta: { ui: { resourceUri: "ui://weather/view.html" } },
|
||||
* },
|
||||
* toolCallback,
|
||||
* );
|
||||
*
|
||||
* // Register the HTML resource the tool references
|
||||
* registerAppResource(
|
||||
* server,
|
||||
* "Weather View",
|
||||
* "ui://weather/view.html",
|
||||
* {},
|
||||
* readCallback,
|
||||
* );
|
||||
* ```
|
||||
*/
|
||||
|
||||
import {
|
||||
|
|
@ -115,13 +135,67 @@ export interface McpUiAppResourceConfig extends ResourceMetadata {
|
|||
* @param cb - Tool handler function
|
||||
*
|
||||
* @example Basic usage
|
||||
* {@includeCode ./index.examples.ts#registerAppTool_basicUsage}
|
||||
* ```ts source="./index.examples.ts#registerAppTool_basicUsage"
|
||||
* registerAppTool(
|
||||
* server,
|
||||
* "get-weather",
|
||||
* {
|
||||
* title: "Get Weather",
|
||||
* description: "Get current weather for a location",
|
||||
* inputSchema: { location: z.string() },
|
||||
* _meta: {
|
||||
* ui: { resourceUri: "ui://weather/view.html" },
|
||||
* },
|
||||
* },
|
||||
* async (args) => {
|
||||
* const weather = await fetchWeather(args.location);
|
||||
* return { content: [{ type: "text", text: JSON.stringify(weather) }] };
|
||||
* },
|
||||
* );
|
||||
* ```
|
||||
*
|
||||
* @example Tool visible to model but not callable by UI
|
||||
* {@includeCode ./index.examples.ts#registerAppTool_modelOnlyVisibility}
|
||||
* ```ts source="./index.examples.ts#registerAppTool_modelOnlyVisibility"
|
||||
* registerAppTool(
|
||||
* server,
|
||||
* "show-cart",
|
||||
* {
|
||||
* description: "Display the user's shopping cart",
|
||||
* _meta: {
|
||||
* ui: {
|
||||
* resourceUri: "ui://shop/cart.html",
|
||||
* visibility: ["model"],
|
||||
* },
|
||||
* },
|
||||
* },
|
||||
* async () => {
|
||||
* const cart = await getCart();
|
||||
* return { content: [{ type: "text", text: JSON.stringify(cart) }] };
|
||||
* },
|
||||
* );
|
||||
* ```
|
||||
*
|
||||
* @example Tool hidden from model, only callable by UI
|
||||
* {@includeCode ./index.examples.ts#registerAppTool_appOnlyVisibility}
|
||||
* ```ts source="./index.examples.ts#registerAppTool_appOnlyVisibility"
|
||||
* registerAppTool(
|
||||
* server,
|
||||
* "update-quantity",
|
||||
* {
|
||||
* description: "Update item quantity in cart",
|
||||
* inputSchema: { itemId: z.string(), quantity: z.number() },
|
||||
* _meta: {
|
||||
* ui: {
|
||||
* resourceUri: "ui://shop/cart.html",
|
||||
* visibility: ["app"],
|
||||
* },
|
||||
* },
|
||||
* },
|
||||
* async ({ itemId, quantity }) => {
|
||||
* const cart = await updateCartItem(itemId, quantity);
|
||||
* return { content: [{ type: "text", text: JSON.stringify(cart) }] };
|
||||
* },
|
||||
* );
|
||||
* ```
|
||||
*
|
||||
* @see {@link registerAppResource `registerAppResource`} to register the HTML resource referenced by the tool
|
||||
*/
|
||||
|
|
@ -170,10 +244,54 @@ export function registerAppTool<
|
|||
* @param readCallback - Callback that returns the resource contents
|
||||
*
|
||||
* @example Basic usage
|
||||
* {@includeCode ./index.examples.ts#registerAppResource_basicUsage}
|
||||
* ```ts source="./index.examples.ts#registerAppResource_basicUsage"
|
||||
* registerAppResource(
|
||||
* server,
|
||||
* "Weather View",
|
||||
* "ui://weather/view.html",
|
||||
* {
|
||||
* description: "Interactive weather display",
|
||||
* },
|
||||
* async () => ({
|
||||
* contents: [
|
||||
* {
|
||||
* uri: "ui://weather/view.html",
|
||||
* mimeType: RESOURCE_MIME_TYPE,
|
||||
* text: await fs.readFile("dist/view.html", "utf-8"),
|
||||
* },
|
||||
* ],
|
||||
* }),
|
||||
* );
|
||||
* ```
|
||||
*
|
||||
* @example With CSP configuration for external domains
|
||||
* {@includeCode ./index.examples.ts#registerAppResource_withCsp}
|
||||
* ```ts source="./index.examples.ts#registerAppResource_withCsp"
|
||||
* registerAppResource(
|
||||
* server,
|
||||
* "Music Player",
|
||||
* "ui://music/player.html",
|
||||
* {
|
||||
* description: "Audio player with external soundfonts",
|
||||
* },
|
||||
* async () => ({
|
||||
* contents: [
|
||||
* {
|
||||
* uri: "ui://music/player.html",
|
||||
* mimeType: RESOURCE_MIME_TYPE,
|
||||
* text: musicPlayerHtml,
|
||||
* _meta: {
|
||||
* ui: {
|
||||
* csp: {
|
||||
* resourceDomains: ["https://cdn.example.com"], // For scripts/styles/images
|
||||
* connectDomains: ["https://api.example.com"], // For fetch/WebSocket
|
||||
* },
|
||||
* },
|
||||
* },
|
||||
* },
|
||||
* ],
|
||||
* }),
|
||||
* );
|
||||
* ```
|
||||
*
|
||||
* @see {@link registerAppTool `registerAppTool`} to register tools that reference this resource
|
||||
*/
|
||||
|
|
|
|||
Loading…
Reference in a new issue