ebay-mcp 1.13.2 → 1.14.0

package/build/scripts/{setup-shared.js → setupShared.js}

@@ -9,8 +9,16 @@ import dotenv from 'dotenv';
  * `v^1.1#i^1#...`, and a naive parser either keeps stray quotes or trips over
  * the `#`. Placeholder values (e.g. `your-client-id_here`) are skipped so the
  * wizard treats them as unset.
+ *
+ * @param projectRoot - Project root containing the `.env` file.
+ * @returns Parsed config values with placeholders removed.
+ *
+ * @example
+ * ```ts
+ * const config = loadExistingConfig(process.cwd());
+ * ```
  */
-export function loadExistingConfig(projectRoot) {
+export const loadExistingConfig = (projectRoot) => {
     const envPath = join(projectRoot, '.env');
     if (!existsSync(envPath)) {
         return {};
@@ -23,7 +31,7 @@ export function loadExistingConfig(projectRoot) {
         }
     }
     return envConfig;
-}
+};
 /**
  * Quote a value for safe inclusion in a `.env` line.
  *
@@ -34,16 +42,30 @@ export function loadExistingConfig(projectRoot) {
  * embedded backslashes and double quotes) so dotenv restores it verbatim. This
  * mirrors the quoting `dotenv-stringify` already applies in the runtime
  * credential store, keeping both `.env` writers consistent.
+ *
+ * @param value - Raw environment value to serialize.
+ * @returns A dotenv-safe value string.
+ *
+ * @example
+ * ```ts
+ * const line = `EBAY_USER_REFRESH_TOKEN=${quoteEnvValue(token)}`;
+ * ```
  */
-export function quoteEnvValue(value) {
+export const quoteEnvValue = (value) => {
     if (value === '' || !/[#\s"'`]/.test(value)) {
         return value;
     }
     return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
-}
+};
 /**
  * Parse environment with safe sandbox default.
+ *
+ * @param value - Optional environment value from config or user input.
+ * @returns `production` only for an exact production value; otherwise `sandbox`.
+ *
+ * @example
+ * ```ts
+ * const environment = readEnvironment(config.EBAY_ENVIRONMENT);
+ * ```
  */
-export function readEnvironment(value) {
-    return value === 'production' ? 'production' : 'sandbox';
-}
+export const readEnvironment = (value) => value === 'production' ? 'production' : 'sandbox';

package/build/scripts/skills.js

@@ -3,27 +3,27 @@ import { resolve } from 'path';
 import { fileURLToPath } from 'url';
 import prompts from 'prompts';
 import { ALL_PROVIDERS, applyWrite, buildRegistrySnapshot, detectProvider, planWrite, providerLabel, renderSkillTargets, } from '../skills/index.js';
-import { ebayPalette, printHeading, printInfo, printRule, printSuccess, printWarning, ui, } from '../utils/cli-ui.js';
+import { ebayPalette, printHeading, printInfo, printRule, printSuccess, printWarning, ui, } from '../utils/cliUi.js';
+import { getErrorMessage } from '../utils/errors.js';
+import { Effect, Either } from 'effect';
+import process from 'node:process';
 const ALL_LAYERS = ['using', 'contributing'];
 /** Splits a comma list flag value into trimmed, non-empty tokens. */
-function parseList(value) {
-    return (value ?? '')
-        .split(',')
-        .map((token) => token.trim())
-        .filter(Boolean);
-}
+const parseList = (value) => (value ?? '')
+    .split(',')
+    .map((token) => token.trim())
+    .filter(Boolean);
 /** Reads the value after a `--flag value` or `--flag=value` argument. */
-function readFlagValue(argv, flag) {
+const readFlagValue = (argv, flag) => {
     const inline = argv.find((arg) => arg.startsWith(`${flag}=`));
     if (inline)
         return inline.slice(flag.length + 1);
     const index = argv.indexOf(flag);
     if (index !== -1 && index + 1 < argv.length)
         return argv[index + 1];
-    return undefined;
-}
+};
 /** Parses skills CLI flags, ignoring the leading `skills` subcommand token. */
-function parseFlags(argv) {
+const parseFlags = (argv) => {
     const args = argv.filter((arg) => arg !== 'skills');
     const providers = parseList(readFlagValue(args, '--providers')).filter((value) => ALL_PROVIDERS.includes(value));
     const layers = parseList(readFlagValue(args, '--layer') ?? readFlagValue(args, '--layers')).filter((value) => ALL_LAYERS.includes(value));
@@ -36,9 +36,9 @@ function parseFlags(argv) {
         providers: providers.length > 0 ? providers : undefined,
         layers: layers.length > 0 ? layers : undefined,
     };
-}
+};
 /** One-line summary of what an action means, for the preview. */
-function actionLabel(action) {
+const actionLabel = (action) => {
     switch (action) {
         case 'create':
             return ui.success('create');
@@ -49,9 +49,9 @@ function actionLabel(action) {
         case 'skip-foreign':
             return ui.warning('skip (foreign file)');
     }
-}
+};
 /** Prints the planned writes so the user can review before anything is written. */
-function printPreview(plans) {
+const printPreview = (plans) => {
     printHeading('Planned changes');
     printRule();
     for (const plan of plans) {
@@ -60,9 +60,9 @@ function printPreview(plans) {
         console.log(`  ${ui.dim('→ ' + plan.target.path)}`);
     }
     printRule();
-}
+};
 /** Prints CLI usage. */
-function printHelp() {
+const printHelp = () => {
     console.log(`
 ${ui.bold('ebay-mcp skills')}  ${ui.dim('install AI skills for Codex, Claude Code, and Cursor')}
 
@@ -84,11 +84,9 @@ ${ui.bold('Examples:')}
   ebay-mcp skills --providers cursor,codex --layer using --dry-run
   ebay-mcp skills --yes
 `);
-}
+};
 /** Resolves the providers to use, preferring flags, else detection at the scope. */
-function resolveDefaultProviders(scope, cwd, home) {
-    return ALL_PROVIDERS.filter((provider) => detectProvider(provider, scope, cwd, home));
-}
+const resolveDefaultProviders = (scope, cwd, home) => ALL_PROVIDERS.filter((provider) => detectProvider(provider, scope, cwd, home));
 /**
  * Runs the skills installer end to end: detect → choose providers/layers/scope →
  * preview → confirm → write. Interactive by default; non-interactive when `--yes`
@@ -97,9 +95,14 @@ function resolveDefaultProviders(scope, cwd, home) {
  * Shared by the `ebay-mcp skills` subcommand, `npm run skills`, and the optional
  * step at the end of `npm run setup`.
  *
- * @param options `argv` overrides process args; `fromSetup` trims the banner.
+ * @param options Runtime overrides for arguments and setup embedding.
+ * @returns A promise that resolves after the installer exits or writes files.
+ * @example
+ * ```ts
+ * await runSkillsWizard({ argv: ['--providers', 'codex', '--yes'] });
+ * ```
  */
-export async function runSkillsWizard(options = {}) {
+export const runSkillsWizard = async (options = {}) => {
     const flags = parseFlags(options.argv ?? process.argv.slice(2));
     if (flags.help) {
         printHelp();
@@ -227,12 +230,17 @@ export async function runSkillsWizard(options = {}) {
     }
     printHeading('Done');
     printInfo(`${written} file(s) written. Restart your AI tool so it picks up the new skills.`);
-}
+};
 const entryPath = process.argv[1] ? resolve(process.argv[1]) : undefined;
 const modulePath = resolve(fileURLToPath(import.meta.url));
 if (entryPath && modulePath === entryPath) {
-    runSkillsWizard().catch((error) => {
-        console.error(ui.error('\n  Skills install failed:'), error);
-        process.exit(1);
+    void Effect.runPromise(Effect.either(Effect.tryPromise({
+        try: () => runSkillsWizard(),
+        catch: (error) => error,
+    }))).then((result) => {
+        if (Either.isLeft(result)) {
+            console.error(ui.error('\n  Skills install failed:'), getErrorMessage(result.left));
+            process.exitCode = 1;
+        }
     });
 }

package/build/scripts/updateApiStatusDoc.js

@@ -0,0 +1,71 @@
+/**
+ * Fetches the eBay API Status RSS feed and writes the latest items to docs/API_STATUS.md.
+ * Used by the GitHub Action to keep an in-repo snapshot. Run with: npx tsx src/scripts/updateApiStatusDoc.ts
+ */
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getApiStatusFeed } from '../utils/apiStatusFeed.js';
+import { getErrorMessage } from '../utils/errors.js';
+import { Data, Effect, Either } from 'effect';
+import process from 'node:process';
+const DEFAULT_LIMIT = 15;
+const OUT_PATH = join(process.cwd(), 'docs', 'API_STATUS.md');
+/** Tagged failure raised while updating the checked-in API status snapshot. */
+class ApiStatusDocUpdateError extends Data.TaggedError('ApiStatusDocUpdateError') {
+}
+function escapeCell(s) {
+    return s.replace(/\|/g, '\\|').replace(/\n/g, ' ');
+}
+function buildMarkdown(items) {
+    const lines = [
+        '# eBay API Status (latest)',
+        '',
+        'Auto-updated snapshot from the [eBay API Status RSS feed](https://developer.ebay.com/rss/api-status).',
+        'Full list: [developer.ebay.com/support/api-status](https://developer.ebay.com/support/api-status).',
+        '',
+        `*Last updated: ${new Date().toISOString()}*`,
+        '',
+        '| Title | API | Site | Status | Last updated | Link |',
+        '|-------|-----|------|--------|--------------|------|',
+    ];
+    for (const item of items) {
+        const link = item.link ? `[Details](${item.link})` : '';
+        lines.push(`| ${escapeCell(item.title)} | ${escapeCell(item.api)} | ${escapeCell(item.site)} | ${escapeCell(item.status)} | ${escapeCell(item.lastUpdated)} | ${link} |`);
+    }
+    lines.push('', '---', '', '*Generated by [ebay-mcp](https://github.com/YosefHayim/ebay-mcp) API status sync.*');
+    return lines.join('\n');
+}
+const updateApiStatusDoc = () => Effect.gen(function* () {
+    const { items, error } = yield* getApiStatusFeed({ limit: DEFAULT_LIMIT }).pipe(Effect.mapError((cause) => new ApiStatusDocUpdateError({
+        message: 'Failed to fetch API status feed',
+        cause,
+    })));
+    if (error && items.length === 0) {
+        return yield* Effect.fail(new ApiStatusDocUpdateError({
+            message: `Failed to fetch API status feed: ${error}`,
+            cause: error,
+        }));
+    }
+    const markdown = buildMarkdown(items);
+    yield* Effect.try({
+        try: () => writeFileSync(OUT_PATH, markdown, 'utf8'),
+        catch: (cause) => new ApiStatusDocUpdateError({
+            message: `Failed to write API status doc to ${OUT_PATH}`,
+            cause,
+        }),
+    });
+    return items.length;
+});
+async function main() {
+    const count = await Effect.runPromise(updateApiStatusDoc());
+    console.log(`Wrote ${count} items to ${OUT_PATH}`);
+}
+void Effect.runPromise(Effect.either(Effect.tryPromise({
+    try: main,
+    catch: (error) => error,
+}))).then((result) => {
+    if (Either.isLeft(result)) {
+        console.error(getErrorMessage(result.left, String(result.left)));
+        process.exitCode = 1;
+    }
+});

package/build/serverHttp.js

@@ -0,0 +1,90 @@
+/**
+ * eBay API MCP Server with HTTP Transport and OAuth 2.1 Authorization.
+ */
+import { resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { validateEnvironmentConfig } from './config/environment.js';
+import { createHttpMcpApp, createHttpTransportConfigFromEnv, getHttpServerUrl, } from './mcp/httpTransport.js';
+import { getErrorMessage } from './utils/errors.js';
+import { serverLogger } from './utils/logger.js';
+import { Effect, Either } from 'effect';
+import process from 'node:process';
+const CONFIG = createHttpTransportConfigFromEnv(process.env);
+function logEnvironmentValidation() {
+    const validation = validateEnvironmentConfig();
+    validation.infos.forEach((info) => {
+        serverLogger.info(info);
+    });
+    if (validation.warnings.length > 0) {
+        serverLogger.warn('Environment Configuration Warnings:');
+        validation.warnings.forEach((warning) => {
+            serverLogger.warn(warning);
+        });
+    }
+    if (!validation.isValid) {
+        serverLogger.error('Environment Configuration Errors:');
+        validation.errors.forEach((error) => {
+            serverLogger.error(error);
+        });
+        serverLogger.error('Please fix the configuration errors and restart the server.');
+        process.exit(1);
+    }
+}
+function logConfiguration() {
+    serverLogger.info('Configuration:');
+    serverLogger.info(`Host: ${CONFIG.host}`);
+    serverLogger.info(`Port: ${CONFIG.port}`);
+    serverLogger.info(`OAuth Enabled: ${CONFIG.authEnabled}`);
+    if (CONFIG.authEnabled) {
+        serverLogger.info(`Auth Server: ${CONFIG.oauth.authServerUrl}`);
+        serverLogger.info(`Required Scopes: ${CONFIG.oauth.requiredScopes.join(', ')}`);
+        serverLogger.info(`Verification Method: ${CONFIG.oauth.useIntrospection ? 'Introspection' : 'JWT'}`);
+    }
+}
+function logStartupUrls(serverUrl) {
+    serverLogger.info('Server is running!');
+    serverLogger.info(`MCP endpoint: ${serverUrl}/`);
+    serverLogger.info(`Protected Resource Metadata: ${serverUrl}/.well-known/oauth-protected-resource`);
+    serverLogger.info(`Health check: ${serverUrl}/health`);
+    if (CONFIG.authEnabled) {
+        serverLogger.info('Authorization is ENABLED');
+        serverLogger.info('Clients must provide valid Bearer tokens to access MCP endpoints');
+    }
+    else {
+        serverLogger.warn('Authorization is DISABLED');
+        serverLogger.warn('Set OAUTH_ENABLED=true (or remove OAUTH_ENABLED=false) to enable OAuth protection');
+    }
+}
+async function main() {
+    const started = await Effect.runPromise(Effect.either(Effect.gen(function* () {
+        serverLogger.info('Starting eBay API MCP Server (HTTP + OAuth)...');
+        logEnvironmentValidation();
+        logConfiguration();
+        const app = yield* Effect.tryPromise({
+            try: () => createHttpMcpApp(CONFIG),
+            catch: (error) => error,
+        });
+        const serverUrl = getHttpServerUrl(CONFIG);
+        const server = app.listen(CONFIG.port, CONFIG.host, () => {
+            logStartupUrls(serverUrl);
+        });
+        process.on('SIGINT', () => {
+            serverLogger.info('Shutting down...');
+            server.close(() => {
+                serverLogger.info('Server closed');
+                process.exit(0);
+            });
+        });
+    })));
+    if (Either.isLeft(started)) {
+        serverLogger.error('Fatal error starting server', {
+            error: getErrorMessage(started.left, String(started.left)),
+        });
+        process.exit(1);
+    }
+}
+const entryPath = process.argv[1] ? resolve(process.argv[1]) : undefined;
+const modulePath = resolve(fileURLToPath(import.meta.url));
+if (entryPath && modulePath === entryPath) {
+    await main();
+}

package/build/skills/content.js

@@ -1,10 +1,10 @@
 /** Renders the live family index as a Markdown table. */
-function familyTable(snapshot) {
+const familyTable = (snapshot) => {
     const rows = snapshot.families
         .map((family) => `| ${family.title} | ${family.count} | ${family.blurb} |`)
         .join('\n');
     return ['| Family | Tools | Covers |', '| --- | --- | --- |', rows].join('\n');
-}
+};
 /**
  * Builds the "using" skill: how a developer's AI should drive the eBay MCP
  * tools. Workflow-first and lean — the per-tool schemas are already visible via
@@ -14,67 +14,70 @@ function familyTable(snapshot) {
  *
  * @param snapshot Live tool count and family index.
  * @returns The provider-neutral skill document.
+ *
+ * @example
+ * ```ts
+ * const doc = buildUsingDoc(snapshot);
+ * ```
  */
-export function buildUsingDoc(snapshot) {
-    return {
-        slug: 'ebay-mcp-using',
-        title: 'Using the eBay MCP tools',
-        description: `Drive eBay's Sell APIs through the ebay-mcp server: ${snapshot.toolCount} tools for listings, orders, marketing, and analytics. Use when creating or revising listings, fulfilling orders, issuing refunds, running Promoted Listings campaigns, or debugging eBay auth/rate-limit errors.`,
-        intro: `The \`ebay-mcp\` server exposes **${snapshot.toolCount} tools across 100% of eBay's Sell APIs**, running locally over MCP. Every tool is named \`ebay_<verb>_<noun>\` (plus two ChatGPT-connector tools, \`search\`/\`fetch\`). You already see each tool's input schema via \`tools/list\` — this skill covers what discovery can't: which tools to chain, what eBay requires first, and how to read its errors.`,
-        sections: [
-            {
-                heading: 'Authentication & environment',
-                body: [
-                    '- **Two auth tiers.** An app token allows ≈1,000 requests/day; user OAuth allows ≈10k–50k/day. Most write operations require user OAuth.',
-                    '- **A 401 / "access denied" is almost always a scope or environment problem**, not a malformed request. Check `ebay_get_token_status`, then re-run `npm run setup` if a scope is missing.',
-                    '- **Sandbox and production are separate worlds** — separate credentials and separate data. Confirm `EBAY_ENVIRONMENT` before investigating "missing" data.',
-                    '- **Marketplace & language headers matter.** Calls honor `EBAY_MARKETPLACE_ID` (e.g. `EBAY_US`) and `Content-Language` (e.g. `en-US`); a wrong pair causes empty or rejected results.',
-                ].join('\n'),
-            },
-            {
-                heading: 'Core workflows',
-                body: [
-                    '**Publish a fixed-price listing (REST Inventory model).**',
-                    '1. One-time account setup: `ebay_opt_in_to_program` (business-policy management), then `ebay_create_payment_policy`, `ebay_create_return_policy`, `ebay_create_fulfillment_policy` for reusable policy IDs, and `ebay_create_or_replace_inventory_location` for a `merchantLocationKey`.',
-                    '2. `ebay_create_inventory_item` (SKU + product details + availability).',
-                    '3. `ebay_create_offer` (SKU, marketplace, price, the policy IDs, location).',
-                    '4. `ebay_publish_offer` (offerId) → a live `listingId`. Use `ebay_bulk_publish_offer` for many at once.',
-                    '',
-                    '**Pick the right category & required item specifics first.**',
-                    '`ebay_get_default_category_tree_id` (marketplace) → `ebay_get_category_suggestions` (query) → `ebay_get_item_aspects_for_category` to learn the required aspects to put on the inventory item.',
-                    '',
-                    '**Fulfill an order.**',
-                    '`ebay_get_orders` (filter unfulfilled) → `ebay_get_order` (detail) → `ebay_create_shipping_fulfillment` (tracking number + carrier).',
-                    '',
-                    '**Refund or handle a payment dispute.**',
-                    'Voluntary refund: `ebay_issue_refund`. Disputes: `ebay_get_payment_dispute_summaries` → `ebay_get_payment_dispute` → `ebay_accept_payment_dispute` (or contest it).',
-                    '',
-                    '**Promote listings (Promoted Listings).**',
-                    '`ebay_create_campaign` → `ebay_bulk_create_ads_by_inventory_reference`. The Marketing family also covers promotions and reports.',
-                    '',
-                    '**Legacy XML path (Trading API).**',
-                    '`ebay_create_listing` / `ebay_revise_listing` / `ebay_relist_item` / `ebay_end_listing`, list via `ebay_get_active_listings`. Use only when you specifically need the legacy flow — do not mix it with the REST Inventory model for the same SKU.',
-                    '',
-                    '**Diagnose failing calls.**',
-                    '`ebay_get_token_status` (auth valid/expiring?) → `ebay_get_rate_limits` / `ebay_get_user_rate_limits` (quota hit?) → `ebay_get_api_status` (eBay-side outage?).',
-                ].join('\n'),
-            },
-            {
-                heading: 'Gotchas & disambiguation',
-                body: [
-                    '- **Two listing models.** REST Inventory (`inventory_item` → `offer` → `publish`) vs legacy Trading (XML). Pick one per SKU and stay in it.',
-                    '- **Offers need policies + a location first.** A "policy not found" error usually means the one-time account setup was skipped.',
-                    '- **`search` and `fetch` are ChatGPT-connector only** — ignore them when driving the Sell API directly.',
-                    '- **Write actions are real.** `publish`, `issue_refund`, `end_listing`, and any `bulk_*` change live seller data — confirm intent before calling.',
-                ].join('\n'),
-            },
-            {
-                heading: `Tool families (${snapshot.toolCount} tools)`,
-                body: familyTable(snapshot),
-            },
-        ],
-    };
-}
+export const buildUsingDoc = (snapshot) => ({
+    slug: 'ebay-mcp-using',
+    title: 'Using the eBay MCP tools',
+    description: `Drive eBay's Sell APIs through the ebay-mcp server: ${snapshot.toolCount} tools for listings, orders, marketing, and analytics. Use when creating or revising listings, fulfilling orders, issuing refunds, running Promoted Listings campaigns, or debugging eBay auth/rate-limit errors.`,
+    intro: `The \`ebay-mcp\` server exposes **${snapshot.toolCount} tools across 100% of eBay's Sell APIs**, running locally over MCP. Every tool is named \`ebay_<verb>_<noun>\` (plus two ChatGPT-connector tools, \`search\`/\`fetch\`). You already see each tool's input schema via \`tools/list\` — this skill covers what discovery can't: which tools to chain, what eBay requires first, and how to read its errors.`,
+    sections: [
+        {
+            heading: 'Authentication & environment',
+            body: [
+                '- **Two auth tiers.** An app token allows ≈1,000 requests/day; user OAuth allows ≈10k–50k/day. Most write operations require user OAuth.',
+                '- **A 401 / "access denied" is almost always a scope or environment problem**, not a malformed request. Check `ebay_get_token_status`, then re-run `npm run setup` if a scope is missing.',
+                '- **Sandbox and production are separate worlds** — separate credentials and separate data. Confirm `EBAY_ENVIRONMENT` before investigating "missing" data.',
+                '- **Marketplace & language headers matter.** Calls honor `EBAY_MARKETPLACE_ID` (e.g. `EBAY_US`) and `Content-Language` (e.g. `en-US`); a wrong pair causes empty or rejected results.',
+            ].join('\n'),
+        },
+        {
+            heading: 'Core workflows',
+            body: [
+                '**Publish a fixed-price listing (REST Inventory model).**',
+                '1. One-time account setup: `ebay_opt_in_to_program` (business-policy management), then `ebay_create_payment_policy`, `ebay_create_return_policy`, `ebay_create_fulfillment_policy` for reusable policy IDs, and `ebay_create_inventory_location` for a `merchantLocationKey`.',
+                '2. `ebay_create_or_replace_inventory_item` (SKU + product details + availability).',
+                '3. `ebay_create_offer` (SKU, marketplace, price, the policy IDs, location).',
+                '4. `ebay_publish_offer` (offerId) → a live `listingId`. Use `ebay_bulk_publish_offer` for many at once.',
+                '',
+                '**Pick the right category & required item specifics first.**',
+                '`ebay_get_default_category_tree_id` (marketplace) → `ebay_get_category_suggestions` (query) → `ebay_get_item_aspects_for_category` to learn the required aspects to put on the inventory item.',
+                '',
+                '**Fulfill an order.**',
+                '`ebay_get_orders` (filter unfulfilled) → `ebay_get_order` (detail) → `ebay_create_shipping_fulfillment` (tracking number + carrier).',
+                '',
+                '**Refund or handle a payment dispute.**',
+                'Voluntary refund: `ebay_issue_refund`. Disputes: `ebay_get_payment_dispute_summaries` → `ebay_get_payment_dispute` → `ebay_accept_payment_dispute` (or contest it).',
+                '',
+                '**Promote listings (Promoted Listings).**',
+                '`ebay_create_campaign` → `ebay_bulk_create_ads_by_inventory_reference`. The Marketing family also covers promotions and reports.',
+                '',
+                '**Legacy XML path (Trading API).**',
+                '`ebay_create_listing` / `ebay_revise_listing` / `ebay_relist_item` / `ebay_end_listing`, list via `ebay_get_active_listings`. Use only when you specifically need the legacy flow — do not mix it with the REST Inventory model for the same SKU.',
+                '',
+                '**Diagnose failing calls.**',
+                '`ebay_get_token_status` (auth valid/expiring?) → `ebay_get_rate_limits` / `ebay_get_user_rate_limits` (quota hit?) → `ebay_get_api_status` (eBay-side outage?).',
+            ].join('\n'),
+        },
+        {
+            heading: 'Gotchas & disambiguation',
+            body: [
+                '- **Two listing models.** REST Inventory (`inventory_item` → `offer` → `publish`) vs legacy Trading (XML). Pick one per SKU and stay in it.',
+                '- **Offers need policies + a location first.** A "policy not found" error usually means the one-time account setup was skipped.',
+                '- **`search` and `fetch` are ChatGPT-connector only** — ignore them when driving the Sell API directly.',
+                '- **Write actions are real.** `publish`, `issue_refund`, `end_listing`, and any `bulk_*` change live seller data — confirm intent before calling.',
+            ].join('\n'),
+        },
+        {
+            heading: `Tool families (${snapshot.toolCount} tools)`,
+            body: familyTable(snapshot),
+        },
+    ],
+});
 /**
  * Builds the "contributing" skill: how an AI working on the ebay-mcp repo should
  * operate. Mirrors AGENTS.md (validation commands, module map, the add-a-tool
@@ -82,60 +85,63 @@ export function buildUsingDoc(snapshot) {
  *
  * @param snapshot Live tool count and family index.
  * @returns The provider-neutral skill document.
+ *
+ * @example
+ * ```ts
+ * const doc = buildContributingDoc(snapshot);
+ * ```
  */
-export function buildContributingDoc(snapshot) {
-    return {
-        slug: 'ebay-mcp-contributing',
-        title: 'Contributing to ebay-mcp',
-        description: `Work on the ebay-mcp server itself: ${snapshot.toolCount} tools across eBay's Sell APIs (TypeScript/ESM, Zod, OpenAPI-generated types). Use when adding or changing eBay tools/endpoints, wiring the registry, or running the project's checks.`,
-        intro: `A local MCP server exposing **${snapshot.toolCount} tools across 100% of eBay's Sell APIs** — TypeScript/Node.js (ESM), \`@modelcontextprotocol/sdk\`, Zod validation, OpenAPI-generated types. Entry points: \`src/index.ts\` (STDIO) and \`src/server-http.ts\` (HTTP).`,
-        sections: [
-            {
-                heading: 'Validation (run before a PR)',
-                body: [
-                    '```bash',
-                    'npm run check     # tsc --noEmit + eslint + prettier --check  (must pass)',
-                    'npm test          # vitest run',
-                    'npm run build     # tsc + tsc-alias → build/',
-                    '```',
-                ].join('\n'),
-            },
-            {
-                heading: 'Module map (`src/`)',
-                body: [
-                    '| Path | Owns |',
-                    '| --- | --- |',
-                    '| `index.ts` / `server-http.ts` | MCP entry points (STDIO / HTTP) |',
-                    '| `api/` | eBay API client implementations (one area per file) |',
-                    '| `auth/` | OAuth 2.0 flow and token management |',
-                    '| `config/` | Environment loading, constants, marketplace defaults |',
-                    '| `tools/` | Tool wiring — `registry.ts`, `contracts.ts`, `define-tool.ts`, and `categories/` (13 family files that co-locate each tool definition with its handler via `defineTool`) |',
-                    "| `skills/` | Agent-skills generator (this skill's source) |",
-                    '| `schemas/` | Shared Zod schemas |',
-                    "| `types/` | TypeScript types — **auto-generated** from OpenAPI specs (don't hand-edit) |",
-                    '| `scripts/` | CLI tooling: `setup.ts`, `skills.ts`, `dev-sync.ts`, `diagnostics.ts` |',
-                    '| `utils/` | Shared utilities (logging, http, errors) |',
-                ].join('\n'),
-            },
-            {
-                heading: 'Add a tool or endpoint',
-                body: [
-                    '1. `npm run sync` — download the latest eBay specs, regenerate types, report missing endpoints.',
-                    '2. Add the API method in `src/api/`.',
-                    '3. Add a `defineTool({ ... handler })` entry in the matching `src/tools/categories/<family>.ts` — definition and handler live together; `registry.ts` derives everything from `categories/index.ts`.',
-                    '4. Add tests in `tests/`.',
-                    '5. `npm run check && npm test`.',
-                ].join('\n'),
-            },
-            {
-                heading: 'Conventions',
-                body: [
-                    '- **No `any`** — specific types; prefer narrowing over assertions. `types/` is generated, so model new shapes from the specs.',
-                    '- Validate tool inputs with Zod; derive related schemas rather than duplicating fields.',
-                    '- Commit with Conventional Commits (releases are changeset-driven).',
-                    '- Logs go to **stderr** only — stdout is reserved for the MCP protocol.',
-                ].join('\n'),
-            },
-        ],
-    };
-}
+export const buildContributingDoc = (snapshot) => ({
+    slug: 'ebay-mcp-contributing',
+    title: 'Contributing to ebay-mcp',
+    description: `Work on the ebay-mcp server itself: ${snapshot.toolCount} tools across eBay's Sell APIs (TypeScript/ESM, Effect-backed validation, OpenAPI-generated types). Use when adding or changing eBay tools/endpoints, wiring the registry, or running the project's checks.`,
+    intro: `A local MCP server exposing **${snapshot.toolCount} tools across 100% of eBay's Sell APIs** — TypeScript/Node.js (ESM), \`@modelcontextprotocol/sdk\`, Effect-backed validation, OpenAPI-generated types. Entry points: \`src/index.ts\` (STDIO) and \`src/serverHttp.ts\` (HTTP).`,
+    sections: [
+        {
+            heading: 'Validation (run before a PR)',
+            body: [
+                '```bash',
+                'npm run check     # tsc --noEmit + eslint + prettier --check  (must pass)',
+                'npm test          # vitest run',
+                'npm run build     # tsc + tsc-alias → build/',
+                '```',
+            ].join('\n'),
+        },
+        {
+            heading: 'Module map (`src/`)',
+            body: [
+                '| Path | Owns |',
+                '| --- | --- |',
+                '| `index.ts` / `serverHttp.ts` | MCP entry points (STDIO / HTTP) |',
+                '| `api/` | eBay API client implementations (one area per file) |',
+                '| `auth/` | OAuth 2.0 flow and token management |',
+                '| `config/` | Environment loading, constants, marketplace defaults |',
+                '| `tools/` | Tool wiring — `registry.ts`, `contracts.ts`, `defineTool.ts`, and `categories/` (13 family files that co-locate each tool definition with its handler via `defineTool`) |',
+                "| `skills/` | Agent-skills generator (this skill's source) |",
+                '| `schemas/` | Shared Effect-backed schemas |',
+                "| `types/` | TypeScript types — **auto-generated** from OpenAPI specs (don't hand-edit) |",
+                '| `scripts/` | CLI tooling: `setup.ts`, `skills.ts`, `devSync.ts`, `diagnostics.ts` |',
+                '| `utils/` | Shared utilities (logging, http, errors) |',
+            ].join('\n'),
+        },
+        {
+            heading: 'Add a tool or endpoint',
+            body: [
+                '1. `npm run sync` — download the latest eBay specs, regenerate types, report missing endpoints.',
+                '2. Add the API method in `src/api/`.',
+                '3. Add a `defineTool({ ... handler })` entry in the matching `src/tools/categories/<family>.ts` — definition and handler live together; `registry.ts` derives everything from `categories/index.ts`.',
+                '4. Add tests in `tests/`.',
+                '5. `npm run check && npm test`.',
+            ].join('\n'),
+        },
+        {
+            heading: 'Conventions',
+            body: [
+                '- **No `any`** — specific types; prefer narrowing over assertions. `types/` is generated, so model new shapes from the specs.',
+                '- Validate tool inputs with Effect-backed schemas from `@/utils/effectSchema.js`; derive related schemas rather than duplicating fields.',
+                '- Commit with Conventional Commits (releases are changeset-driven).',
+                '- Logs go to **stderr** only — stdout is reserved for the MCP protocol.',
+            ].join('\n'),
+        },
+    ],
+});