docs: add tool visibility and restructure _meta.ui (#131)
* docs: add tool visibility and restructure _meta.ui - Restructure tool metadata: `_meta["ui/resourceUri"]` → `_meta.ui.resourceUri` - Add `visibility` array field: ["model"], ["apps"], or ["model", "apps"] - Default ["model"] preserves standard MCP behavior - ["apps"] enables widget-only tools hidden from agent - Add McpUiToolMeta interface for type safety - Add Design Decision #4 explaining approach vs OpenAI's two-field model 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * address PR review comments - Change default visibility to ["model", "apps"] - Add deprecation notice for flat ui/resourceUri format - Add McpUiToolMeta and McpUiToolVisibility to spec.types.ts - Improve tools/list and tools/call behavior wording 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * chore: regenerate schemas for McpUiToolMeta types 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * feat: tool visibility and nested _meta.ui format - Rename visibility "apps" → "app" in McpUiToolVisibility type - Add _meta.ui.resourceUri nested format (deprecate flat format) - Add getToolUiResourceUri() utility with backward compatibility - Add visibility demo to system-monitor-server: - get-system-stats: visibility ["model"] with resourceUri - refresh-stats: visibility ["app"] (app-only polling) - Update all example servers to use new _meta.ui format - Add 11 unit tests for getToolUiResourceUri() 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * chore: regenerate schemas with updated dependencies * feat: export McpUiToolMeta type and add type annotations - Export McpUiToolMeta and McpUiToolVisibility types from types.ts - Export corresponding Zod schemas (McpUiToolMetaSchema, McpUiToolVisibilitySchema) - Add `as McpUiToolMeta` type annotations to all example servers - Update docs/quickstart.md with proper typing Ensures type safety for `_meta.ui` tool metadata across the codebase. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * feat: add server helpers and optional connect() transport Add `src/server/` with convenience functions for registering MCP App tools and resources: - `registerAppTool(server, name, config, handler)` - `registerAppResource(server, name, uri, config, callback)` The `transport` parameter in `App.connect()` is now optional, defaulting to `PostMessageTransport(window.parent)`. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Update src/server/index.ts Co-authored-by: Jonathan Hefner <jonathan@hefner.pro> * feat: update McpUiAppToolConfig to support both _meta.ui and flat formats * refactor: simplify server helper imports * docs: add deprecation notice and improve resourceUri documentation * feat: add backward compat normalization in registerAppTool - If _meta.ui.resourceUri is set, also set legacy flat key - If legacy flat key is set, also set _meta.ui.resourceUri - Preserves existing visibility when merging - Does not overwrite if both formats already set * refactor: avoid mutating config arg in registerAppTool * style: format with prettier --------- Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: Olivier Chafik <ochafik@anthropic.com> Co-authored-by: Jonathan Hefner <jonathan@hefner.pro>
This commit is contained in:
Anton Pidkuiko
GitHub
parent
bea0ae27f5
commit
37aab03de0
2 changed files with 530 additions and 43 deletions
|
|
@ -52,6 +52,147 @@ describe("registerAppTool", () => {
|
|||
).toBe("ui://test/widget.html");
|
||||
expect(capturedHandler).toBe(handler);
|
||||
});
|
||||
|
||||
describe("backward compatibility", () => {
|
||||
it("should set legacy key when _meta.ui.resourceUri is provided", () => {
|
||||
let capturedConfig: Record<string, unknown> | undefined;
|
||||
|
||||
const mockServer = {
|
||||
registerTool: mock(
|
||||
(
|
||||
_name: string,
|
||||
config: Record<string, unknown>,
|
||||
_handler: unknown,
|
||||
) => {
|
||||
capturedConfig = config;
|
||||
},
|
||||
),
|
||||
};
|
||||
|
||||
registerAppTool(
|
||||
mockServer as unknown as Pick<McpServer, "registerTool">,
|
||||
"my-tool",
|
||||
{
|
||||
_meta: {
|
||||
ui: { resourceUri: "ui://test/widget.html" },
|
||||
},
|
||||
},
|
||||
async () => ({ content: [{ type: "text" as const, text: "ok" }] }),
|
||||
);
|
||||
|
||||
const meta = capturedConfig?._meta as Record<string, unknown>;
|
||||
// New format should be preserved
|
||||
expect((meta.ui as { resourceUri: string }).resourceUri).toBe(
|
||||
"ui://test/widget.html",
|
||||
);
|
||||
// Legacy key should also be set
|
||||
expect(meta[RESOURCE_URI_META_KEY]).toBe("ui://test/widget.html");
|
||||
});
|
||||
|
||||
it("should set _meta.ui.resourceUri when legacy key is provided", () => {
|
||||
let capturedConfig: Record<string, unknown> | undefined;
|
||||
|
||||
const mockServer = {
|
||||
registerTool: mock(
|
||||
(
|
||||
_name: string,
|
||||
config: Record<string, unknown>,
|
||||
_handler: unknown,
|
||||
) => {
|
||||
capturedConfig = config;
|
||||
},
|
||||
),
|
||||
};
|
||||
|
||||
registerAppTool(
|
||||
mockServer as unknown as Pick<McpServer, "registerTool">,
|
||||
"my-tool",
|
||||
{
|
||||
_meta: {
|
||||
[RESOURCE_URI_META_KEY]: "ui://test/widget.html",
|
||||
},
|
||||
},
|
||||
async () => ({ content: [{ type: "text" as const, text: "ok" }] }),
|
||||
);
|
||||
|
||||
const meta = capturedConfig?._meta as Record<string, unknown>;
|
||||
// Legacy key should be preserved
|
||||
expect(meta[RESOURCE_URI_META_KEY]).toBe("ui://test/widget.html");
|
||||
// New format should also be set
|
||||
expect((meta.ui as { resourceUri: string }).resourceUri).toBe(
|
||||
"ui://test/widget.html",
|
||||
);
|
||||
});
|
||||
|
||||
it("should preserve visibility when converting from legacy format", () => {
|
||||
let capturedConfig: Record<string, unknown> | undefined;
|
||||
|
||||
const mockServer = {
|
||||
registerTool: mock(
|
||||
(
|
||||
_name: string,
|
||||
config: Record<string, unknown>,
|
||||
_handler: unknown,
|
||||
) => {
|
||||
capturedConfig = config;
|
||||
},
|
||||
),
|
||||
};
|
||||
|
||||
registerAppTool(
|
||||
mockServer as unknown as Pick<McpServer, "registerTool">,
|
||||
"my-tool",
|
||||
{
|
||||
_meta: {
|
||||
ui: { visibility: ["app"] },
|
||||
[RESOURCE_URI_META_KEY]: "ui://test/widget.html",
|
||||
},
|
||||
} as any,
|
||||
async () => ({ content: [{ type: "text" as const, text: "ok" }] }),
|
||||
);
|
||||
|
||||
const meta = capturedConfig?._meta as Record<string, unknown>;
|
||||
const ui = meta.ui as { resourceUri: string; visibility: string[] };
|
||||
// Should have merged resourceUri into existing ui object
|
||||
expect(ui.resourceUri).toBe("ui://test/widget.html");
|
||||
expect(ui.visibility).toEqual(["app"]);
|
||||
});
|
||||
|
||||
it("should not overwrite if both formats are already set", () => {
|
||||
let capturedConfig: Record<string, unknown> | undefined;
|
||||
|
||||
const mockServer = {
|
||||
registerTool: mock(
|
||||
(
|
||||
_name: string,
|
||||
config: Record<string, unknown>,
|
||||
_handler: unknown,
|
||||
) => {
|
||||
capturedConfig = config;
|
||||
},
|
||||
),
|
||||
};
|
||||
|
||||
registerAppTool(
|
||||
mockServer as unknown as Pick<McpServer, "registerTool">,
|
||||
"my-tool",
|
||||
{
|
||||
_meta: {
|
||||
ui: { resourceUri: "ui://new/widget.html" },
|
||||
[RESOURCE_URI_META_KEY]: "ui://old/widget.html",
|
||||
},
|
||||
} as any,
|
||||
async () => ({ content: [{ type: "text" as const, text: "ok" }] }),
|
||||
);
|
||||
|
||||
const meta = capturedConfig?._meta as Record<string, unknown>;
|
||||
// Both should remain unchanged
|
||||
expect((meta.ui as { resourceUri: string }).resourceUri).toBe(
|
||||
"ui://new/widget.html",
|
||||
);
|
||||
expect(meta[RESOURCE_URI_META_KEY]).toBe("ui://old/widget.html");
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe("registerAppResource", () => {
|
||||
|
|
|
|||
|
|
@ -8,6 +8,7 @@ import {
|
|||
RESOURCE_URI_META_KEY,
|
||||
RESOURCE_MIME_TYPE,
|
||||
McpUiResourceMeta,
|
||||
McpUiToolMeta,
|
||||
} from "../app.js";
|
||||
import type {
|
||||
McpServer,
|
||||
|
|
@ -38,25 +39,31 @@ export interface ToolConfig {
|
|||
*/
|
||||
export interface McpUiAppToolConfig extends ToolConfig {
|
||||
_meta: {
|
||||
// Soon: `ui: McpUiToolMeta;` (https://github.com/modelcontextprotocol/ext-apps/pull/131)
|
||||
|
||||
/**
|
||||
* URI of the UI resource to display for this tool.
|
||||
* This is converted to `_meta["ui/resourceUri"]`.
|
||||
*
|
||||
* @example "ui://weather/widget.html"
|
||||
*/
|
||||
[RESOURCE_URI_META_KEY]: string;
|
||||
[key: string]: unknown;
|
||||
};
|
||||
} & (
|
||||
| {
|
||||
ui: McpUiToolMeta;
|
||||
}
|
||||
| {
|
||||
/**
|
||||
* URI of the UI resource to display for this tool.
|
||||
* This is converted to `_meta["ui/resourceUri"]`.
|
||||
*
|
||||
* @example "ui://weather/widget.html"
|
||||
*
|
||||
* @deprecated Use `_meta.ui.resourceUri` instead.
|
||||
*/
|
||||
[RESOURCE_URI_META_KEY]?: string;
|
||||
}
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* MCP App Resource configuration for `registerAppResource`.
|
||||
*/
|
||||
export interface McpUiAppResourceConfig extends ResourceMetadata {
|
||||
_meta?: {
|
||||
ui?: McpUiResourceMeta;
|
||||
_meta: {
|
||||
ui: McpUiResourceMeta;
|
||||
[key: string]: unknown;
|
||||
};
|
||||
}
|
||||
|
|
@ -95,7 +102,23 @@ export function registerAppTool(
|
|||
config: McpUiAppToolConfig,
|
||||
handler: ToolCallback<ZodRawShape>,
|
||||
): void {
|
||||
server.registerTool(name, config, handler);
|
||||
// Normalize metadata for backward compatibility:
|
||||
// - If _meta.ui.resourceUri is set, also set the legacy flat key
|
||||
// - If the legacy flat key is set, also set _meta.ui.resourceUri
|
||||
const meta = config._meta;
|
||||
const uiMeta = meta.ui as McpUiToolMeta | undefined;
|
||||
const legacyUri = meta[RESOURCE_URI_META_KEY] as string | undefined;
|
||||
|
||||
let normalizedMeta = meta;
|
||||
if (uiMeta?.resourceUri && !legacyUri) {
|
||||
// New format -> also set legacy key
|
||||
normalizedMeta = { ...meta, [RESOURCE_URI_META_KEY]: uiMeta.resourceUri };
|
||||
} else if (legacyUri && !uiMeta?.resourceUri) {
|
||||
// Legacy format -> also set new format
|
||||
normalizedMeta = { ...meta, ui: { ...uiMeta, resourceUri: legacyUri } };
|
||||
}
|
||||
|
||||
server.registerTool(name, { ...config, _meta: normalizedMeta }, handler);
|
||||
}
|
||||
|
||||
/**
|
||||
|
|
|
|||
Loading…
Reference in a new issue