ebay-mcp 1.11.1 → 1.13.0

package/build/mcp/runtime.js

@@ -1,6 +1,9 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { EbaySellerApi } from '../api/index.js';
 import { getEbayConfig, mcpConfig } from '../config/environment.js';
+import { resolveToolGatingMode } from '../config/tool-families.js';
+import { createToolGatingController, DYNAMIC_MODE_INSTRUCTIONS, registerMetaTools, toolNamesInFamilies, } from '../mcp/tool-gating.js';
+import { buildUiToolResult, createUiBridge } from '../mcp/ui-bridge.js';
 import { getToolEntries } from '../tools/registry.js';
 import { getErrorMessage } from '../utils/errors.js';
 import { serverLogger, toolLogger } from '../utils/logger.js';
@@ -26,9 +29,11 @@ function formatToolFailure(error) {
         isError: true,
     };
 }
-function registerTool(server, api, entry, logToolExecution) {
+function registerTool(server, api, entry, logToolExecution, ui) {
     const { definition, handler } = entry;
-    server.registerTool(definition.name, {
+    // Registered plainly (no UI `_meta`) so every host gets a working text tool by
+    // default; the capability gate later flips `_meta.ui` on for UI-capable clients.
+    const registered = server.registerTool(definition.name, {
         description: definition.description,
         inputSchema: definition.inputSchema,
     }, async (args) => {
@@ -40,7 +45,9 @@ function registerTool(server, api, entry, logToolExecution) {
             if (logToolExecution) {
                 toolLogger.debug(`Tool ${definition.name} completed successfully`);
             }
-            return formatToolSuccess(result);
+            return ui.shouldRender(entry)
+                ? buildUiToolResult(entry.ui, result)
+                : formatToolSuccess(result);
         }
         catch (error) {
             const errorMessage = getErrorMessage(error);
@@ -50,18 +57,55 @@ function registerTool(server, api, entry, logToolExecution) {
             return formatToolFailure(error);
         }
     });
+    ui.register(entry, registered);
+    return registered;
 }
 /**
  * Create an MCP server runtime and register all eBay tool handlers.
  */
 export function createEbayMcpRuntime(options = {}) {
     const api = options.api ?? new EbaySellerApi(getEbayConfig());
-    const server = new McpServer(options.serverConfig ?? mcpConfig);
-    const entries = getToolEntries();
-    serverLogger.info(`Registering ${entries.length} tools`);
+    const serverInfo = options.serverConfig ?? mcpConfig;
+    const mode = resolveToolGatingMode();
+    // Instructions are set only in dynamic mode so the agent knows the catalogue is
+    // hidden behind the discovery tools; default/static modes keep the handshake
+    // byte-for-byte unchanged (a bare single-arg construction).
+    const server = mode.kind === 'dynamic'
+        ? new McpServer(serverInfo, { instructions: DYNAMIC_MODE_INSTRUCTIONS })
+        : new McpServer(serverInfo);
+    const ui = createUiBridge(server, import.meta.url);
+    // Static mode registers only the named families; all and dynamic register the
+    // full catalogue (dynamic then disables it below, before the transport connects).
+    const allEntries = getToolEntries();
+    const entries = mode.kind === 'static'
+        ? (() => {
+            const names = toolNamesInFamilies(mode.families);
+            return allEntries.filter((entry) => names.has(entry.definition.name));
+        })()
+        : allEntries;
+    const handles = new Map();
     for (const entry of entries) {
-        registerTool(server, api, entry, options.logToolExecution ?? false);
+        handles.set(entry.definition.name, registerTool(server, api, entry, options.logToolExecution ?? false, ui));
     }
+    if (mode.kind === 'dynamic') {
+        // Disable before `connect`: the SDK only emits `tools/listChanged` once the
+        // transport is connected, so these flips are silent. The agent re-enables the
+        // tools it needs via the meta-tools, which fire `listChanged` post-connect.
+        for (const handle of handles.values()) {
+            handle.disable();
+        }
+        registerMetaTools(server, createToolGatingController(handles));
+        serverLogger.info(`Dynamic tool mode: ${handles.size} eBay tools hidden behind 3 discovery tools`);
+    }
+    else if (mode.kind === 'static') {
+        serverLogger.info(`Static tool mode: registered ${handles.size} tools from families: ${mode.families.join(', ')}`);
+    }
+    else {
+        serverLogger.info(`Registering ${handles.size} tools`);
+    }
+    // Install after registration so every UI-eligible tool is captured before the
+    // gate can flip their metadata on a UI-capable client's `initialize`.
+    ui.installCapabilityGate();
     return {
         api,
         server,

package/build/mcp/tool-gating.js

@@ -0,0 +1,198 @@
+import { z } from 'zod';
+import { TOOL_FAMILY_KEYS } from '../config/tool-families.js';
+import { toolCategories } from '../tools/categories/index.js';
+/**
+ * Tool gating: the runtime half of the `EBAY_MCP_TOOLS=dynamic` feature.
+ *
+ * In dynamic mode the server registers every eBay tool but boots with them
+ * disabled, advertising only the three discovery meta-tools defined here. The
+ * agent browses the catalogue and enables just the tools it needs; the MCP SDK
+ * emits `tools/listChanged` automatically when a tool's `enabled` flag flips, so
+ * the host re-fetches and the freshly enabled tools appear natively, with their
+ * real input schemas and validation. This keeps advertised context proportional
+ * to what the agent actually uses instead of the full ~187-tool catalogue.
+ *
+ * The pure env parsing/validation lives in `@/config/tool-families.ts`; this
+ * module owns everything that needs the live tool registry.
+ */
+/** Default page size for {@link ToolGatingController.list} when `limit` is omitted. */
+const DEFAULT_LIST_LIMIT = 25;
+/** Upper bound on a single discovery page, mirrored by the `list_ebay_tools` schema. */
+const MAX_LIST_LIMIT = 100;
+/**
+ * Initialize-time guidance shown to the agent in dynamic mode so it knows the
+ * catalogue is hidden behind the discovery tools. Set only when dynamic mode is
+ * active; the default and static modes leave the handshake untouched.
+ */
+export const DYNAMIC_MODE_INSTRUCTIONS = 'This eBay server keeps its full tool catalogue hidden to save context. Only the discovery tools are visible right now. ' +
+    'Call `list_ebay_tools` (no arguments) to see the tool families, then `list_ebay_tools` with a `family` or `query` to find specific tools, ' +
+    'then `enable_ebay_tools` with the tool names you need — they will appear as normal tools you can call. ' +
+    'Call `disable_ebay_tools` to remove tools you no longer need and reclaim context.';
+/** Condenses a tool description to a single sentence for the discovery listing. */
+function toSummary(description) {
+    const firstLine = description.split('\n', 1)[0].trim();
+    const sentenceEnd = firstLine.indexOf('. ');
+    const sentence = sentenceEnd === -1 ? firstLine : firstLine.slice(0, sentenceEnd + 1);
+    return sentence.length > 160 ? `${sentence.slice(0, 157)}...` : sentence;
+}
+/** Builds the discovery catalogue (tool rows, family overview, name→family index). */
+function buildCatalog() {
+    const rows = [];
+    const families = [];
+    const familyByToolName = new Map();
+    for (const category of toolCategories) {
+        families.push({ key: category.key, title: category.title, count: category.entries.length });
+        for (const entry of category.entries) {
+            const { name, description } = entry.definition;
+            rows.push({ name, family: category.key, summary: toSummary(description) });
+            familyByToolName.set(name, category.key);
+        }
+    }
+    return { rows, families, familyByToolName };
+}
+const CATALOG = buildCatalog();
+/**
+ * Resolves the tool names belonging to the given families, preserving the caller's
+ * ability to filter registry entries for static mode. Unknown family keys
+ * contribute nothing (they are rejected earlier by env validation).
+ */
+export function toolNamesInFamilies(families) {
+    const wanted = new Set(families);
+    const names = new Set();
+    for (const [name, family] of CATALOG.familyByToolName) {
+        if (wanted.has(family)) {
+            names.add(name);
+        }
+    }
+    return names;
+}
+/** Parses an opaque list cursor (a stringified offset) back into a non-negative offset. */
+function parseCursor(cursor) {
+    if (!cursor) {
+        return 0;
+    }
+    const offset = Number.parseInt(cursor, 10);
+    return Number.isInteger(offset) && offset > 0 ? offset : 0;
+}
+/**
+ * Creates the controller backing the discovery meta-tools.
+ *
+ * @param handles - Map of eBay tool name → its registered handle. Only these tools
+ *   are gateable; the meta-tools themselves are intentionally absent so they can
+ *   never be disabled and are excluded from `activeCount`.
+ */
+export function createToolGatingController(handles) {
+    const activeCount = () => [...handles.values()].filter((handle) => handle.enabled).length;
+    const mutate = (names, enable) => {
+        const changed = [];
+        const unknown = [];
+        for (const name of names) {
+            const handle = handles.get(name);
+            if (!handle) {
+                unknown.push(name);
+                continue;
+            }
+            if (handle.enabled !== enable) {
+                if (enable) {
+                    handle.enable();
+                }
+                else {
+                    handle.disable();
+                }
+            }
+            changed.push(name);
+        }
+        return enable
+            ? { enabled: changed, unknown, activeCount: activeCount() }
+            : { disabled: changed, unknown, activeCount: activeCount() };
+    };
+    return {
+        list({ family, query, cursor, limit }) {
+            if (!family && !query) {
+                return {
+                    families: CATALOG.families.map((row) => ({
+                        ...row,
+                        enabledCount: [...handles.entries()].filter(([name, handle]) => CATALOG.familyByToolName.get(name) === row.key && handle.enabled).length,
+                    })),
+                    hint: 'Call list_ebay_tools with { family } or { query } to list tools, then enable_ebay_tools.',
+                };
+            }
+            if (family && !CATALOG.families.some((row) => row.key === family)) {
+                return {
+                    error: `Unknown tool family "${family}".`,
+                    validFamilies: TOOL_FAMILY_KEYS,
+                };
+            }
+            const needle = query?.toLowerCase();
+            const matches = CATALOG.rows.filter((row) => {
+                if (family && row.family !== family) {
+                    return false;
+                }
+                if (needle) {
+                    return (row.name.toLowerCase().includes(needle) ||
+                        row.summary.toLowerCase().includes(needle) ||
+                        row.family.includes(needle));
+                }
+                return true;
+            });
+            const offset = parseCursor(cursor);
+            const size = Math.min(limit ?? DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT);
+            const page = matches.slice(offset, offset + size);
+            const nextOffset = offset + size;
+            return {
+                tools: page.map((row) => ({ ...row, enabled: handles.get(row.name)?.enabled ?? false })),
+                total: matches.length,
+                nextCursor: nextOffset < matches.length ? String(nextOffset) : undefined,
+            };
+        },
+        enable: (names) => mutate(names, true),
+        disable: (names) => mutate(names, false),
+    };
+}
+/** Wraps controller output as a standard text tool result. */
+function toToolResult(data) {
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+}
+/**
+ * Registers the three discovery meta-tools on the server. Called only in dynamic
+ * mode, after the eBay tools are registered and disabled, so the controller sees
+ * every gateable handle.
+ */
+export function registerMetaTools(server, controller) {
+    server.registerTool('list_ebay_tools', {
+        description: "Discover eBay tools without loading them into context. Call with no arguments to list the tool families; pass `family` to list a family's tools, or `query` to keyword-search across all tools. Returns lightweight rows (name, family, summary) — enable a tool with enable_ebay_tools to get its full schema and call it.",
+        inputSchema: {
+            family: z
+                .string()
+                .optional()
+                .describe('Restrict results to one family key (e.g. "inventory").'),
+            query: z
+                .string()
+                .optional()
+                .describe('Case-insensitive keyword matched against tool name, summary, and family.'),
+            cursor: z.string().optional().describe('Pagination cursor from a prior call.'),
+            limit: z
+                .number()
+                .int()
+                .positive()
+                .max(MAX_LIST_LIMIT)
+                .optional()
+                .describe(`Max rows per page (default ${DEFAULT_LIST_LIMIT}, max ${MAX_LIST_LIMIT}).`),
+        },
+    }, (args) => toToolResult(controller.list(args)));
+    server.registerTool('enable_ebay_tools', {
+        description: 'Load specific eBay tools into context so they can be called. Pass the exact tool names from list_ebay_tools. Returns the names enabled, any unknown names, and the active tool count.',
+        inputSchema: {
+            names: z
+                .array(z.string())
+                .min(1)
+                .describe('Exact tool names to enable, as returned by list_ebay_tools.'),
+        },
+    }, ({ names }) => toToolResult(controller.enable(names)));
+    server.registerTool('disable_ebay_tools', {
+        description: 'Unload eBay tools previously enabled, reclaiming their context. Pass the exact tool names. Returns the names disabled, any unknown names, and the active tool count.',
+        inputSchema: {
+            names: z.array(z.string()).min(1).describe('Exact tool names to disable.'),
+        },
+    }, ({ names }) => toToolResult(controller.disable(names)));
+}

package/build/mcp/ui-bridge.js

@@ -0,0 +1,151 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getUiCapability, registerAppResource, RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY, } from '@modelcontextprotocol/ext-apps/server';
+import { uiArchetypes } from '../tools/ui/archetypes.js';
+import { serverLogger } from '../utils/logger.js';
+/**
+ * Decides whether interactive views should be advertised to the connected client.
+ *
+ * Pure and injectable (capabilities + env) so the gate is unit-testable without a
+ * live transport. Two independent conditions must both hold: the operator has not
+ * disabled UI via `EBAY_MCP_UI=off`, and the client advertised support for the MCP
+ * Apps HTML profile.
+ */
+export function resolveUiEnabled(capabilities, env = process.env) {
+    if (env.EBAY_MCP_UI === 'off') {
+        return false;
+    }
+    const capability = getUiCapability(capabilities);
+    return Boolean(capability?.mimeTypes?.includes(RESOURCE_MIME_TYPE));
+}
+/**
+ * Builds the one-line text fallback that accompanies a rendered view.
+ *
+ * Hosts that render the app show this line in the transcript; the model reads it
+ * plus the structured `structuredContent`. Keeping it a short summary (rather than
+ * re-dumping the full JSON the view already carries) is what keeps the UI path
+ * from costing more tokens than the plain path.
+ */
+export function summarizeView(view) {
+    switch (view.archetype) {
+        case 'table': {
+            const count = view.rows.length;
+            const tail = view.footnote ? ` — ${view.footnote}` : '';
+            return `${view.title ?? 'Results'}: ${count} ${count === 1 ? 'row' : 'rows'}${tail}. Rendered as an interactive table.`;
+        }
+        case 'card': {
+            const subtitle = view.subtitle ? ` — ${view.subtitle}` : '';
+            const fieldCount = view.sections.reduce((total, section) => total + section.fields.length, 0);
+            return `${view.title ?? 'Details'}${subtitle}: ${fieldCount} ${fieldCount === 1 ? 'field' : 'fields'}. Rendered as an interactive detail card.`;
+        }
+        case 'chart': {
+            const pointCount = view.series.reduce((total, series) => total + series.points.length, 0);
+            return `${view.title ?? 'Chart'} (${view.kind}): ${view.series.length} series, ${pointCount} ${pointCount === 1 ? 'point' : 'points'}. Rendered as an interactive chart.`;
+        }
+    }
+}
+/**
+ * Adapts a {@link ViewModel} to the SDK's open-record `structuredContent` type.
+ *
+ * A view model is a string-keyed JSON object by construction, but TypeScript does
+ * not give `interface` types an implicit string index signature, so it refuses the
+ * direct cast. The `unknown` hop is the standard, safe bridge across that gap —
+ * preferable to polluting every view-model interface with `[key: string]: unknown`,
+ * which would silently disable excess-property checks in the tool mappers.
+ */
+function asStructuredContent(view) {
+    return view;
+}
+/**
+ * Projects a tool result into its view and packages it as a UI tool result: a
+ * compact summary line, the view model as `structuredContent`, and the
+ * `_meta.ui.resourceUri` that tells the host which app to render.
+ */
+export function buildUiToolResult(ui, result) {
+    const view = ui.map(result);
+    return {
+        content: [{ type: 'text', text: summarizeView(view) }],
+        structuredContent: asStructuredContent(view),
+        _meta: { ui: { resourceUri: ui.resourceUri } },
+    };
+}
+/**
+ * Walks up from `startDir` to the nearest directory containing a `package.json`.
+ * Used to locate the repo root so built views resolve identically whether the
+ * server runs from `build/` (prod) or `src/` via tsx (dev).
+ */
+export function findRepoRoot(startDir) {
+    let current = startDir;
+    for (;;) {
+        if (existsSync(join(current, 'package.json'))) {
+            return current;
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            return undefined;
+        }
+        current = parent;
+    }
+}
+/** Resolves the directory that holds the built archetype HTML files (`build/ui/`). */
+export function resolveBuiltUiDir(moduleUrl) {
+    const fromDir = dirname(fileURLToPath(moduleUrl));
+    const root = findRepoRoot(fromDir);
+    return root ? join(root, 'build', 'ui') : join(fromDir, '..', 'ui');
+}
+/**
+ * Constructs the {@link UiBridge}: reads the built archetype HTML, registers each
+ * found view as a `ui://` resource, and returns the runtime-facing facade.
+ *
+ * @param server - The MCP server the resources and gate attach to.
+ * @param moduleUrl - `import.meta.url` of the caller, used to locate `build/ui/`.
+ */
+export function createUiBridge(server, moduleUrl) {
+    const builtUiDir = resolveBuiltUiDir(moduleUrl);
+    const available = new Set();
+    // `Object.keys` widens to `string[]`; the cast restores the manifest's key type.
+    for (const archetype of Object.keys(uiArchetypes)) {
+        const { uri, name, htmlFile } = uiArchetypes[archetype];
+        const htmlPath = join(builtUiDir, htmlFile);
+        if (!existsSync(htmlPath)) {
+            serverLogger.warn(`UI view not built; "${uri}" disabled (expected ${htmlPath})`);
+            continue;
+        }
+        const html = readFileSync(htmlPath, 'utf-8');
+        registerAppResource(server, name, uri, {}, () => ({
+            contents: [{ uri, mimeType: RESOURCE_MIME_TYPE, text: html }],
+        }));
+        available.add(archetype);
+    }
+    let uiEnabled = false;
+    const uiTools = [];
+    return {
+        register(entry, registered) {
+            if (entry.ui && available.has(entry.ui.archetype)) {
+                uiTools.push({ registered, resourceUri: entry.ui.resourceUri });
+            }
+        },
+        shouldRender(entry) {
+            return uiEnabled && entry.ui != null && available.has(entry.ui.archetype);
+        },
+        installCapabilityGate() {
+            const priorOnInitialized = server.server.oninitialized;
+            server.server.oninitialized = () => {
+                priorOnInitialized?.();
+                uiEnabled = resolveUiEnabled(server.server.getClientCapabilities());
+                if (!uiEnabled) {
+                    return;
+                }
+                for (const { registered, resourceUri } of uiTools) {
+                    registered.update({
+                        _meta: {
+                            ui: { resourceUri },
+                            [RESOURCE_URI_META_KEY]: resourceUri,
+                        },
+                    });
+                }
+            };
+        },
+    };
+}

package/build/scripts/build-ui.js

@@ -0,0 +1,44 @@
+/**
+ * Builds the three interactive MCP Apps views into self-contained HTML files
+ * under `build/ui/`.
+ *
+ * Why a script rather than a single `vite.config.ts`: `vite-plugin-singlefile`
+ * inlines all dynamic imports, which Rollup only permits with a single input.
+ * The three archetypes are therefore built one at a time (each its own
+ * single-page build) into a shared output directory — the first pass clears it,
+ * the rest append. The result is exactly what `src/mcp/ui-bridge.ts` expects:
+ * `build/ui/{table,card,chart}.html`, each with its JS and CSS inlined so the
+ * server can serve it verbatim as a `ui://` resource with no sibling requests.
+ *
+ * Run via `npm run build:ui` (also chained into `npm run build`).
+ */
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { build } from 'vite';
+import { viteSingleFile } from 'vite-plugin-singlefile';
+import { uiArchetypes } from '../tools/ui/archetypes.js';
+import { serverLogger } from '../utils/logger.js';
+const scriptsDir = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(scriptsDir, '../..');
+const uiDir = resolve(repoRoot, 'ui');
+const outDir = resolve(repoRoot, 'build', 'ui');
+/** Vite config for a single archetype's single-page, fully-inlined build. */
+function configFor(archetype, clean) {
+    return {
+        root: uiDir,
+        configFile: false,
+        logLevel: 'warn',
+        plugins: [viteSingleFile()],
+        esbuild: { jsx: 'automatic', jsxImportSource: 'react' },
+        build: {
+            outDir,
+            emptyOutDir: clean,
+            rollupOptions: { input: resolve(uiDir, uiArchetypes[archetype].htmlFile) },
+        },
+    };
+}
+const archetypes = Object.keys(uiArchetypes);
+for (const [index, archetype] of archetypes.entries()) {
+    await build(configFor(archetype, index === 0));
+    serverLogger.info(`Built UI view "${uiArchetypes[archetype].htmlFile}"`);
+}

package/build/tools/categories/analytics.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { defineTool } from '../../tools/define-tool.js';
+import { mapCustomerServiceMetricToChart, mapStandardsProfileToCard, mapTrafficReportToChart, } from '../../tools/ui/maps.js';
 /** Analytics API tools for seller traffic and performance reporting. */
 export const analyticsEntries = [
     defineTool({
@@ -20,6 +21,7 @@ export const analyticsEntries = [
             description: 'Traffic report data',
         },
         handler: (api, args) => api.analytics.getTrafficReport(args.dimension, args.filter, args.metric, args.sort),
+        ui: { archetype: 'chart', map: mapTrafficReportToChart },
     }),
     defineTool({
         name: 'ebay_find_seller_standards_profiles',
@@ -51,6 +53,7 @@ export const analyticsEntries = [
             description: 'Seller standards profile data',
         },
         handler: (api, args) => api.analytics.getSellerStandardsProfile(args.program, args.cycle),
+        ui: { archetype: 'card', map: mapStandardsProfileToCard },
     }),
     defineTool({
         name: 'ebay_get_customer_service_metric',
@@ -68,5 +71,6 @@ export const analyticsEntries = [
             description: 'Customer service metric data',
         },
         handler: (api, args) => api.analytics.getCustomerServiceMetric(args.customerServiceMetricType, args.evaluationType, args.evaluationMarketplaceId),
+        ui: { archetype: 'chart', map: mapCustomerServiceMetricToChart },
     }),
 ];

package/build/tools/categories/fulfillment.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { zodToJsonSchema } from 'zod-to-json-schema';
 import { defineTool } from '../../tools/define-tool.js';
+import { mapDisputeSummariesToTable, mapDisputeToCard, mapFulfillmentsToTable, mapOrdersToTable, mapOrderToCard, } from '../../tools/ui/maps.js';
 import { shippingFulfillmentSchema } from '../schemas.js';
 import { getOrdersOutputSchema, getOrderOutputSchema, createShippingFulfillmentOutputSchema, getShippingFulfillmentsOutputSchema, issueRefundOutputSchema, getPaymentDisputesOutputSchema, } from '../../schemas/fulfillment/orders.js';
 /** Fulfillment API tools for orders, shipping fulfillments, refunds, and cancellations. */
@@ -21,6 +22,7 @@ export const fulfillmentEntries = [
             $refStrategy: 'none',
         }),
         handler: (api, args) => api.fulfillment.getOrders(args.filter, args.limit, args.offset),
+        ui: { archetype: 'table', map: mapOrdersToTable },
     }),
     defineTool({
         name: 'ebay_get_order',
@@ -33,6 +35,7 @@ export const fulfillmentEntries = [
             $refStrategy: 'none',
         }),
         handler: (api, args) => api.fulfillment.getOrder(args.orderId),
+        ui: { archetype: 'card', map: mapOrderToCard },
     }),
     defineTool({
         name: 'ebay_create_shipping_fulfillment',
@@ -58,6 +61,7 @@ export const fulfillmentEntries = [
             $refStrategy: 'none',
         }),
         handler: (api, args) => api.fulfillment.getShippingFulfillments(args.orderId),
+        ui: { archetype: 'table', map: mapFulfillmentsToTable },
     }),
     defineTool({
         name: 'ebay_get_shipping_fulfillment',
@@ -157,6 +161,7 @@ export const fulfillmentEntries = [
             limit: args.limit,
             offset: args.offset,
         }),
+        ui: { archetype: 'table', map: mapDisputeSummariesToTable },
     }),
     defineTool({
         name: 'ebay_get_payment_dispute',
@@ -176,6 +181,7 @@ export const fulfillmentEntries = [
             description: 'Payment dispute details',
         },
         handler: (api, args) => api.dispute.getPaymentDispute(args.paymentDisputeId),
+        ui: { archetype: 'card', map: mapDisputeToCard },
     }),
     defineTool({
         name: 'ebay_get_payment_dispute_activities',

package/build/tools/categories/inventory.js

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { zodToJsonSchema } from 'zod-to-json-schema';
 import { MarketplaceId } from '../../types/ebay-enums.js';
 import { defineTool } from '../../tools/define-tool.js';
+import { mapInventoryItemsToTable, mapInventoryItemToCard, mapLocationsToTable, mapOffersToTable, mapOfferToCard, } from '../../tools/ui/maps.js';
 import { bulkInventoryItemRequestSchema, bulkMigrateRequestSchema, bulkOfferRequestSchema, bulkPriceQuantityRequestSchema, bulkPublishRequestSchema, inventoryItemGroupSchema, inventoryItemSchema, listingFeesRequestSchema, locationSchema, offerSchema, productCompatibilitySchema, } from '../schemas.js';
 import { getInventoryItemsOutputSchema, getInventoryItemOutputSchema, createInventoryItemOutputSchema, getOffersOutputSchema, createOfferOutputSchema, publishOfferOutputSchema, offerResponseSchema, getInventoryLocationsOutputSchema, createInventoryLocationOutputSchema, getProductCompatibilityOutputSchema, getInventoryItemGroupOutputSchema, bulkInventoryItemResponseSchema, bulkOfferResponseSchema, bulkPublishResponseSchema, } from '../../schemas/inventory-management/inventory.js';
 /** Inventory API tools for seller inventory items, offers, locations, and bulk operations. */
@@ -18,6 +19,7 @@ export const inventoryEntries = [
             $refStrategy: 'none',
         }),
         handler: (api, args) => api.inventory.getInventoryItems(args.limit, args.offset),
+        ui: { archetype: 'table', map: mapInventoryItemsToTable },
     }),
     defineTool({
         name: 'ebay_get_inventory_item',
@@ -30,6 +32,7 @@ export const inventoryEntries = [
             $refStrategy: 'none',
         }),
         handler: (api, args) => api.inventory.getInventoryItem(args.sku),
+        ui: { archetype: 'card', map: mapInventoryItemToCard },
     }),
     defineTool({
         name: 'ebay_create_inventory_item',
@@ -70,6 +73,7 @@ export const inventoryEntries = [
             $refStrategy: 'none',
         }),
         handler: (api, args) => api.inventory.getOffers(args.sku, args.marketplaceId, args.limit),
+        ui: { archetype: 'table', map: mapOffersToTable },
     }),
     defineTool({
         name: 'ebay_create_offer',
@@ -232,6 +236,7 @@ export const inventoryEntries = [
             $refStrategy: 'none',
         }),
         handler: (api, args) => api.inventory.getInventoryLocations(args.limit, args.offset),
+        ui: { archetype: 'table', map: mapLocationsToTable },
     }),
     defineTool({
         name: 'ebay_get_inventory_location',
@@ -322,6 +327,7 @@ export const inventoryEntries = [
             $refStrategy: 'none',
         }),
         handler: (api, args) => api.inventory.getOffer(args.offerId),
+        ui: { archetype: 'card', map: mapOfferToCard },
     }),
     defineTool({
         name: 'ebay_update_offer',

package/build/tools/define-tool.js

@@ -1,4 +1,21 @@
 import { z } from 'zod';
+import { uiArchetypes } from '../tools/ui/archetypes.js';
+/**
+ * Erases the compile-time result type from a {@link ToolUiSpec} so the binding can
+ * live on the non-generic {@link ToolEntry}, and resolves the archetype's
+ * `resourceUri` from the single-source-of-truth {@link uiArchetypes} manifest.
+ *
+ * The `result as Result` cast is the type-erasure boundary: at runtime `map` only
+ * ever receives the very value its own handler returned, so the cast restores the
+ * type the mapper was written and type-checked against.
+ */
+function resolveToolUi(ui) {
+    return {
+        archetype: ui.archetype,
+        resourceUri: uiArchetypes[ui.archetype].uri,
+        map: (result) => ui.map(result),
+    };
+}
 /**
  * Binds a tool's Zod input shape to its handler so the shape is the single
  * source of truth for both the advertised MCP schema and the handler's
@@ -38,7 +55,11 @@ export function defineTool(spec) {
     // the caller's `await`, and the handler's returned promise passes straight
     // through without an extra await layer.
     const handler = (api, args) => spec.handler(api, schema.parse(args));
-    return { definition: toDefinition(spec), handler };
+    return {
+        definition: toDefinition(spec),
+        handler,
+        ui: spec.ui ? resolveToolUi(spec.ui) : undefined,
+    };
 }
 /**
  * Like {@link defineTool}, but invokes the handler with the raw transport
@@ -57,5 +78,9 @@ export function defineTool(spec) {
  */
 export function rawTool(spec) {
     const handler = (api, args) => spec.handler(api, args);
-    return { definition: toDefinition(spec), handler };
+    return {
+        definition: toDefinition(spec),
+        handler,
+        ui: spec.ui ? resolveToolUi(spec.ui) : undefined,
+    };
 }

package/build/tools/ui/archetypes.js

@@ -0,0 +1,11 @@
+/**
+ * The archetype manifest — the authoritative map from {@link ViewArchetype} to its
+ * resource URI and built asset. Both `defineTool` (to resolve a tool's
+ * `resourceUri`) and the runtime seam (to register resources and gate emission)
+ * read from here, so the two halves can never disagree on a URI or filename.
+ */
+export const uiArchetypes = {
+    table: { uri: 'ui://ebay/table.html', name: 'eBay table view', htmlFile: 'table.html' },
+    card: { uri: 'ui://ebay/card.html', name: 'eBay detail card view', htmlFile: 'card.html' },
+    chart: { uri: 'ui://ebay/chart.html', name: 'eBay chart view', htmlFile: 'chart.html' },
+};