ebay-mcp 1.12.0 → 1.13.0

package/README.md

@@ -205,8 +205,21 @@ EBAY_MARKETPLACE_ID=EBAY_US         # default marketplace (overridable per tool)
 EBAY_CONTENT_LANGUAGE=en-US         # default request content language
 EBAY_USER_REFRESH_TOKEN=your_token  # for higher rate limits
 EBAY_MCP_UI=on                      # interactive MCP Apps views (beta); "off" forces plain JSON
+EBAY_MCP_TOOLS=all                  # tool exposure: "all", "dynamic", or a family list (see below)
 ```
 
+### Tool exposure (`EBAY_MCP_TOOLS`)
+
+By default all tools are advertised to the agent at once. On a long conversation that catalogue is a meaningful slice of the context window, so two opt-in modes let you shrink it:
+
+| Value                       | Behavior                                                                                                                                               | Works on                                |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
+| `all` _(default, or unset)_ | Every tool advertised at startup.                                                                                                                      | every host                              |
+| `dynamic`                   | Only three discovery tools are visible (`list_ebay_tools`, `enable_ebay_tools`, `disable_ebay_tools`). The agent searches the catalogue and loads only the tools it needs; they then appear natively. | hosts that honor `tools/listChanged` (e.g. Claude) |
+| `inventory,fulfillment,…`   | Registers **only** the named families (listed below), frozen for the session.                                                                          | every host (incl. ChatGPT, Cursor)      |
+
+The family list is literal — you get exactly what you name. ChatGPT connectors need the `connector` family (its `search`/`fetch` tools); add it explicitly, e.g. `EBAY_MCP_TOOLS=connector,inventory`. An unknown family name fails fast at startup with the valid list. Valid families: `connector`, `token-management`, `account`, `inventory`, `fulfillment`, `marketing`, `analytics`, `metadata`, `taxonomy`, `communication`, `other`, `developer`, `trading`.
+
 ### Authentication & rate limits
 
 | Mode                             | Daily limit     | Best for                | Setup                             |

package/build/config/environment.js

@@ -3,6 +3,7 @@ import { existsSync, readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
 import { LocaleEnum } from '../types/ebay-enums.js';
+import { getToolGatingConfigError } from '../config/tool-families.js';
 import { getVersion } from '../utils/version.js';
 import { getErrorMessage } from '../utils/errors.js';
 // Get the current directory for loading scope files and .env
@@ -126,6 +127,11 @@ export function validateEnvironmentConfig() {
     if (!process.env.EBAY_REDIRECT_URI) {
         warnings.push('EBAY_REDIRECT_URI is not set. User OAuth flow will not work. Set this to enable user token generation.');
     }
+    // Validate EBAY_MCP_TOOLS (all | dynamic | comma-separated family list)
+    const toolGatingError = getToolGatingConfigError();
+    if (toolGatingError) {
+        errors.push(toolGatingError);
+    }
     // Validate that scope files exist
     try {
         getProductionScopes();

package/build/config/tool-families.js

@@ -0,0 +1,79 @@
+/**
+ * Tool-family contract for the `EBAY_MCP_TOOLS` env var.
+ *
+ * This module is deliberately free of any import from the tool tree
+ * (`@/tools/*`). `config/environment.ts` validates `EBAY_MCP_TOOLS` and is itself
+ * imported by tool handlers (e.g. `tools/categories/token-management.ts`), so
+ * pulling the registry in here would create an import cycle. The heavier pieces
+ * that genuinely need the registry — the discovery catalogue and the meta-tools —
+ * live in `@/mcp/tool-gating.ts`, which imports these primitives.
+ *
+ * The family keys below must stay in lock-step with `toolCategories`; a unit test
+ * asserts the two agree so adding a category without updating this list fails CI.
+ */
+/**
+ * Canonical tool-family keys, mirroring `toolCategories[].key`. These are the
+ * accepted tokens in a static `EBAY_MCP_TOOLS` list (e.g. `inventory,fulfillment`).
+ */
+export const TOOL_FAMILY_KEYS = [
+    'connector',
+    'token-management',
+    'account',
+    'inventory',
+    'fulfillment',
+    'marketing',
+    'analytics',
+    'metadata',
+    'taxonomy',
+    'communication',
+    'other',
+    'developer',
+    'trading',
+];
+const FAMILY_KEY_SET = new Set(TOOL_FAMILY_KEYS);
+/** Splits a raw `EBAY_MCP_TOOLS` list into trimmed, lowercased, non-empty tokens. */
+function parseFamilyTokens(raw) {
+    return raw
+        .split(',')
+        .map((token) => token.trim().toLowerCase())
+        .filter(Boolean);
+}
+/**
+ * Resolves `EBAY_MCP_TOOLS` into a {@link ToolGatingMode}.
+ *
+ * Parsing is lenient by design — unknown family tokens are kept in the returned
+ * `static` mode so the dedicated validator ({@link getToolGatingConfigError}) can
+ * report them precisely. Callers that act on the mode should treat only
+ * {@link TOOL_FAMILY_KEYS} members as registerable.
+ */
+export function resolveToolGatingMode(env = process.env) {
+    const raw = env.EBAY_MCP_TOOLS?.trim();
+    if (!raw || raw.toLowerCase() === 'all') {
+        return { kind: 'all' };
+    }
+    if (raw.toLowerCase() === 'dynamic') {
+        return { kind: 'dynamic' };
+    }
+    return { kind: 'static', families: parseFamilyTokens(raw) };
+}
+/**
+ * Validates `EBAY_MCP_TOOLS` and returns a human-readable error string, or
+ * `undefined` when the value is valid. Surfaced through
+ * `validateEnvironmentConfig` so a typo fails loudly at startup (server exits)
+ * rather than silently leaving the agent with fewer tools than intended.
+ */
+export function getToolGatingConfigError(env = process.env) {
+    const mode = resolveToolGatingMode(env);
+    if (mode.kind !== 'static') {
+        return undefined;
+    }
+    if (mode.families.length === 0) {
+        return `EBAY_MCP_TOOLS is set but lists no tool families. Use "all", "dynamic", or a comma-separated list of: ${TOOL_FAMILY_KEYS.join(', ')}.`;
+    }
+    const unknown = mode.families.filter((family) => !FAMILY_KEY_SET.has(family));
+    if (unknown.length === 0) {
+        return undefined;
+    }
+    const noun = unknown.length === 1 ? 'family' : 'families';
+    return `EBAY_MCP_TOOLS contains unknown tool ${noun}: ${unknown.join(', ')}. Valid families: ${TOOL_FAMILY_KEYS.join(', ')}.`;
+}

package/build/mcp/runtime.js

@@ -1,6 +1,8 @@
 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';
@@ -56,18 +58,50 @@ function registerTool(server, api, entry, logToolExecution, ui) {
         }
     });
     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();
+    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);
-    serverLogger.info(`Registering ${entries.length} tools`);
+    // 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, ui);
+        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`.

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ebay-mcp",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "Model Context Protocol (MCP) server that exposes 100% of eBay's Sell APIs (322 tools across 270 endpoints) to AI assistants like Claude, Cursor, and Cline, covering inventory, order fulfillment, marketing, analytics, and developer tools with OAuth authentication and refresh-token support.",
   "type": "module",
   "main": "build/index.js",