@iflow-mcp/dynamicendpoints-etsy-mcp 1.2.0

package/src/index.ts

@@ -0,0 +1,2667 @@
+#!/usr/bin/env node
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+  Tool,
+  Prompt,
+  Resource,
+  GetPromptResult,
+  ReadResourceResult,
+} from '@modelcontextprotocol/sdk/types.js';
+import axios, { AxiosInstance } from 'axios';
+import { z } from 'zod';
+
+// Etsy API Configuration
+const ETSY_API_BASE_URL = 'https://openapi.etsy.com/v3';
+
+interface EtsyConfig {
+  apiKey: string;
+  shopId?: string;
+  accessToken?: string;
+}
+
+// Configuration schema for Smithery - All fields optional
+export const configSchema = z.object({
+  apiKey: z.string().optional().describe('Your Etsy API key (Keystring) from the Etsy Developer Portal. Falls back to ETSY_API_KEY environment variable.'),
+  shopId: z.string().optional().describe('Your Etsy shop ID (optional, for faster shop operations). Falls back to ETSY_SHOP_ID environment variable.'),
+  accessToken: z.string().optional().describe('OAuth access token for shop management features (optional, required for write operations). Falls back to ETSY_ACCESS_TOKEN environment variable.'),
+});
+
+class EtsyMCPServer {
+  private server: Server;
+  private axiosInstance: AxiosInstance;
+  private config: EtsyConfig;
+
+  constructor(config: EtsyConfig) {
+    this.config = config;
+
+    const headers: any = {
+      'x-api-key': this.config.apiKey,
+    };
+
+    // Add OAuth token if available for authenticated requests
+    if (this.config.accessToken) {
+      headers['Authorization'] = `Bearer ${this.config.accessToken}`;
+    }
+
+    this.axiosInstance = axios.create({
+      baseURL: ETSY_API_BASE_URL,
+      headers,
+    });
+
+    this.server = new Server(
+      {
+        name: 'etsy-mcp-server',
+        version: '1.0.0',
+      },
+      {
+        capabilities: {
+          tools: {},
+          prompts: {},
+          resources: {},
+        },
+      }
+    );
+
+    this.setupHandlers();
+  }
+
+  private setupHandlers(): void {
+    // List available tools
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+      tools: this.getTools(),
+    }));
+
+    // Handle tool calls
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const { name, arguments: args } = request.params;
+
+      try {
+        switch (name) {
+          case 'search_listings':
+            return await this.searchListings(args);
+          case 'get_listing':
+            return await this.getListing(args);
+          case 'get_shop':
+            return await this.getShop(args);
+          case 'get_shop_listings':
+            return await this.getShopListings(args);
+          case 'search_shops':
+            return await this.searchShops(args);
+          case 'get_listing_inventory':
+            return await this.getListingInventory(args);
+          case 'get_listing_images':
+            return await this.getListingImages(args);
+          case 'get_shop_sections':
+            return await this.getShopSections(args);
+          case 'get_trending_listings':
+            return await this.getTrendingListings(args);
+          case 'find_shops':
+            return await this.findShops(args);
+          // Shop Management Tools
+          case 'create_listing':
+            return await this.createListing(args);
+          case 'update_listing':
+            return await this.updateListing(args);
+          case 'delete_listing':
+            return await this.deleteListing(args);
+          case 'update_listing_inventory':
+            return await this.updateListingInventory(args);
+          case 'upload_listing_image':
+            return await this.uploadListingImage(args);
+          case 'create_shop_section':
+            return await this.createShopSection(args);
+          case 'update_shop_section':
+            return await this.updateShopSection(args);
+          case 'delete_shop_section':
+            return await this.deleteShopSection(args);
+          case 'update_shop':
+            return await this.updateShop(args);
+          default:
+            throw new Error(`Unknown tool: ${name}`);
+        }
+      } catch (error) {
+        if (axios.isAxiosError(error)) {
+          return {
+            content: [
+              {
+                type: 'text',
+                text: JSON.stringify(
+                  {
+                    error: error.response?.data || error.message,
+                    status: error.response?.status,
+                  },
+                  null,
+                  2
+                ),
+              },
+            ],
+          };
+        }
+        throw error;
+      }
+    });
+
+    // List available prompts
+    this.server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+      prompts: this.getPrompts(),
+    }));
+
+    // Handle prompt requests
+    this.server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+      const { name, arguments: args } = request.params;
+      return await this.getPrompt(name, args);
+    });
+
+    // List available resources
+    this.server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+      resources: this.getResources(),
+    }));
+
+    // Handle resource reads
+    this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+      const { uri } = request.params;
+      return await this.readResource(uri);
+    });
+  }
+
+  private getTools(): Tool[] {
+    return [
+      {
+        name: 'search_listings',
+        description:
+          'Search for active Etsy listings. Supports keyword search with various filters.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            keywords: {
+              type: 'string',
+              description: 'Search keywords for finding listings',
+            },
+            limit: {
+              type: 'number',
+              description: 'Maximum number of results (default: 25, max: 100)',
+              default: 25,
+            },
+            offset: {
+              type: 'number',
+              description: 'Number of results to skip (for pagination)',
+              default: 0,
+            },
+            min_price: {
+              type: 'number',
+              description: 'Minimum price in the shop currency',
+            },
+            max_price: {
+              type: 'number',
+              description: 'Maximum price in the shop currency',
+            },
+            sort_on: {
+              type: 'string',
+              enum: ['created', 'price', 'updated', 'score'],
+              description: 'Field to sort results on',
+            },
+            sort_order: {
+              type: 'string',
+              enum: ['asc', 'desc', 'ascending', 'descending'],
+              description: 'Sort order',
+            },
+          },
+          required: ['keywords'],
+        },
+        annotations: {
+          readOnlyHint: true,
+          destructiveHint: false,
+          idempotentHint: true,
+        },
+      },
+      {
+        name: 'get_listing',
+        description: 'Get detailed information about a specific Etsy listing by its ID.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            listing_id: {
+              type: 'number',
+              description: 'The numeric ID of the listing',
+            },
+            includes: {
+              type: 'array',
+              items: {
+                type: 'string',
+                enum: ['Shop', 'Images', 'User', 'Translations', 'Inventory'],
+              },
+              description: 'Additional data to include in the response',
+            },
+          },
+          required: ['listing_id'],
+        },
+        annotations: {
+          readOnlyHint: true,
+          destructiveHint: false,
+          idempotentHint: true,
+        },
+      },
+      {
+        name: 'get_shop',
+        description: 'Get information about an Etsy shop by shop ID.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            shop_id: {
+              type: 'number',
+              description: 'The numeric ID of the shop',
+            },
+          },
+          required: ['shop_id'],
+        },
+        annotations: {
+          readOnlyHint: true,
+          destructiveHint: false,
+          idempotentHint: true,
+        },
+      },
+      {
+        name: 'get_shop_listings',
+        description: 'Get all active listings from a specific shop.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            shop_id: {
+              type: 'number',
+              description: 'The numeric ID of the shop',
+            },
+            limit: {
+              type: 'number',
+              description: 'Maximum number of results (default: 25, max: 100)',
+              default: 25,
+            },
+            offset: {
+              type: 'number',
+              description: 'Number of results to skip (for pagination)',
+              default: 0,
+            },
+            state: {
+              type: 'string',
+              enum: ['active', 'inactive', 'sold_out', 'draft', 'expired'],
+              description: 'Filter by listing state (default: active)',
+              default: 'active',
+            },
+          },
+          required: ['shop_id'],
+        },
+        annotations: {
+          readOnlyHint: true,
+          destructiveHint: false,
+          idempotentHint: true,
+        },
+      },
+      {
+        name: 'search_shops',
+        description: 'Search for Etsy shops by shop name.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            shop_name: {
+              type: 'string',
+              description: 'The shop name to search for',
+            },
+            limit: {
+              type: 'number',
+              description: 'Maximum number of results (default: 25, max: 100)',
+              default: 25,
+            },
+            offset: {
+              type: 'number',
+              description: 'Number of results to skip (for pagination)',
+              default: 0,
+            },
+          },
+          required: ['shop_name'],
+        },
+        annotations: {
+          readOnlyHint: true,
+          destructiveHint: false,
+          idempotentHint: true,
+        },
+      },
+      {
+        name: 'get_listing_inventory',
+        description:
+          'Get inventory information for a listing, including available quantities and variations.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            listing_id: {
+              type: 'number',
+              description: 'The numeric ID of the listing',
+            },
+          },
+          required: ['listing_id'],
+        },
+        annotations: {
+          readOnlyHint: true,
+          destructiveHint: false,
+          idempotentHint: true,
+        },
+      },
+      {
+        name: 'get_listing_images',
+        description: 'Get all images associated with a specific listing.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            listing_id: {
+              type: 'number',
+              description: 'The numeric ID of the listing',
+            },
+          },
+          required: ['listing_id'],
+        },
+        annotations: {
+          readOnlyHint: true,
+          destructiveHint: false,
+          idempotentHint: true,
+        },
+      },
+      {
+        name: 'get_shop_sections',
+        description: 'Get all sections/categories for a specific shop.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            shop_id: {
+              type: 'number',
+              description: 'The numeric ID of the shop',
+            },
+          },
+          required: ['shop_id'],
+        },
+        annotations: {
+          readOnlyHint: true,
+          destructiveHint: false,
+          idempotentHint: true,
+        },
+      },
+      {
+        name: 'get_trending_listings',
+        description: 'Get current trending listings on Etsy.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            limit: {
+              type: 'number',
+              description: 'Maximum number of results (default: 25, max: 100)',
+              default: 25,
+            },
+            offset: {
+              type: 'number',
+              description: 'Number of results to skip (for pagination)',
+              default: 0,
+            },
+          },
+        },
+        annotations: {
+          readOnlyHint: true,
+          destructiveHint: false,
+          idempotentHint: true,
+        },
+      },
+      {
+        name: 'find_shops',
+        description: 'Find shops by location or other criteria.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            location: {
+              type: 'string',
+              description: 'Location to search for shops',
+            },
+            limit: {
+              type: 'number',
+              description: 'Maximum number of results (default: 25, max: 100)',
+              default: 25,
+            },
+            offset: {
+              type: 'number',
+              description: 'Number of results to skip (for pagination)',
+              default: 0,
+            },
+          },
+        },
+        annotations: {
+          readOnlyHint: true,
+          destructiveHint: false,
+          idempotentHint: true,
+        },
+      },
+      // Shop Management Tools (require OAuth access token)
+      {
+        name: 'create_listing',
+        description:
+          'Create a new listing in your Etsy shop. Requires OAuth access token.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            shop_id: {
+              type: 'number',
+              description: 'Your shop ID',
+            },
+            quantity: {
+              type: 'number',
+              description: 'Available quantity',
+            },
+            title: {
+              type: 'string',
+              description: 'Listing title (max 140 characters)',
+            },
+            description: {
+              type: 'string',
+              description: 'Item description',
+            },
+            price: {
+              type: 'number',
+              description: 'Price in shop currency',
+            },
+            who_made: {
+              type: 'string',
+              enum: ['i_did', 'someone_else', 'collective'],
+              description: 'Who made this item',
+            },
+            when_made: {
+              type: 'string',
+              description:
+                'When was it made (e.g., made_to_order, 2020_2023, 2010_2019)',
+            },
+            taxonomy_id: {
+              type: 'number',
+              description: 'Category taxonomy ID',
+            },
+            shipping_profile_id: {
+              type: 'number',
+              description: 'Shipping profile ID (optional)',
+            },
+            shop_section_id: {
+              type: 'number',
+              description: 'Shop section ID (optional)',
+            },
+            tags: {
+              type: 'array',
+              items: { type: 'string' },
+              description: 'Array of tags (max 13)',
+            },
+          },
+          required: [
+            'shop_id',
+            'quantity',
+            'title',
+            'description',
+            'price',
+            'who_made',
+            'when_made',
+            'taxonomy_id',
+          ],
+        },
+        annotations: {
+          readOnlyHint: false,
+          destructiveHint: false,
+          idempotentHint: false,
+        },
+      },
+      {
+        name: 'update_listing',
+        description: 'Update an existing listing. Requires OAuth access token.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            shop_id: {
+              type: 'number',
+              description: 'Your shop ID',
+            },
+            listing_id: {
+              type: 'number',
+              description: 'Listing ID to update',
+            },
+            title: {
+              type: 'string',
+              description: 'New title',
+            },
+            description: {
+              type: 'string',
+              description: 'New description',
+            },
+            price: {
+              type: 'number',
+              description: 'New price',
+            },
+            quantity: {
+              type: 'number',
+              description: 'New quantity',
+            },
+            tags: {
+              type: 'array',
+              items: { type: 'string' },
+              description: 'New tags',
+            },
+            shop_section_id: {
+              type: 'number',
+              description: 'Shop section ID',
+            },
+          },
+          required: ['shop_id', 'listing_id'],
+        },
+        annotations: {
+          readOnlyHint: false,
+          destructiveHint: false,
+          idempotentHint: true,
+        },
+      },
+      {
+        name: 'delete_listing',
+        description:
+          'Delete a listing from your shop. Requires OAuth access token.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            listing_id: {
+              type: 'number',
+              description: 'Listing ID to delete',
+            },
+          },
+          required: ['listing_id'],
+        },
+        annotations: {
+          readOnlyHint: false,
+          destructiveHint: true,
+          idempotentHint: true,
+        },
+      },
+      {
+        name: 'update_listing_inventory',
+        description:
+          'Update inventory for a listing (quantities, prices, SKUs). Requires OAuth access token.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            listing_id: {
+              type: 'number',
+              description: 'Listing ID',
+            },
+            products: {
+              type: 'array',
+              description: 'Array of product variations with offerings',
+              items: {
+                type: 'object',
+                properties: {
+                  sku: { type: 'string' },
+                  property_values: {
+                    type: 'array',
+                    items: {
+                      type: 'object',
+                      properties: {
+                        property_id: { type: 'number' },
+                        property_name: { type: 'string' },
+                        scale_id: { type: 'number' },
+                        value_ids: {
+                          type: 'array',
+                          items: { type: 'number' },
+                        },
+                        values: {
+                          type: 'array',
+                          items: { type: 'string' },
+                        },
+                      },
+                    },
+                  },
+                  offerings: {
+                    type: 'array',
+                    items: {
+                      type: 'object',
+                      properties: {
+                        price: { type: 'number' },
+                        quantity: { type: 'number' },
+                        is_enabled: { type: 'boolean' },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+            price_on_property: {
+              type: 'array',
+              items: { type: 'number' },
+              description: 'Property IDs that affect price',
+            },
+            quantity_on_property: {
+              type: 'array',
+              items: { type: 'number' },
+              description: 'Property IDs that affect quantity',
+            },
+            sku_on_property: {
+              type: 'array',
+              items: { type: 'number' },
+              description: 'Property IDs that affect SKU',
+            },
+          },
+          required: ['listing_id', 'products'],
+        },
+        annotations: {
+          readOnlyHint: false,
+          destructiveHint: false,
+          idempotentHint: true,
+        },
+      },
+      {
+        name: 'upload_listing_image',
+        description:
+          'Upload an image to a listing. Requires OAuth access token and image file.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            shop_id: {
+              type: 'number',
+              description: 'Your shop ID',
+            },
+            listing_id: {
+              type: 'number',
+              description: 'Listing ID',
+            },
+            image_url: {
+              type: 'string',
+              description: 'URL of the image to upload',
+            },
+            rank: {
+              type: 'number',
+              description: 'Display order (1 = primary image)',
+            },
+            alt_text: {
+              type: 'string',
+              description: 'Alternative text for accessibility',
+            },
+          },
+          required: ['shop_id', 'listing_id', 'image_url'],
+        },
+        annotations: {
+          readOnlyHint: false,
+          destructiveHint: false,
+          idempotentHint: false,
+        },
+      },
+      {
+        name: 'create_shop_section',
+        description:
+          'Create a new shop section/category. Requires OAuth access token.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            shop_id: {
+              type: 'number',
+              description: 'Your shop ID',
+            },
+            title: {
+              type: 'string',
+              description: 'Section title',
+            },
+          },
+          required: ['shop_id', 'title'],
+        },
+        annotations: {
+          readOnlyHint: false,
+          destructiveHint: false,
+          idempotentHint: false,
+        },
+      },
+      {
+        name: 'update_shop_section',
+        description: 'Update a shop section. Requires OAuth access token.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            shop_id: {
+              type: 'number',
+              description: 'Your shop ID',
+            },
+            shop_section_id: {
+              type: 'number',
+              description: 'Section ID to update',
+            },
+            title: {
+              type: 'string',
+              description: 'New section title',
+            },
+          },
+          required: ['shop_id', 'shop_section_id', 'title'],
+        },
+        annotations: {
+          readOnlyHint: false,
+          destructiveHint: false,
+          idempotentHint: true,
+        },
+      },
+      {
+        name: 'delete_shop_section',
+        description: 'Delete a shop section. Requires OAuth access token.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            shop_id: {
+              type: 'number',
+              description: 'Your shop ID',
+            },
+            shop_section_id: {
+              type: 'number',
+              description: 'Section ID to delete',
+            },
+          },
+          required: ['shop_id', 'shop_section_id'],
+        },
+        annotations: {
+          readOnlyHint: false,
+          destructiveHint: true,
+          idempotentHint: true,
+        },
+      },
+      {
+        name: 'update_shop',
+        description:
+          'Update shop information (title, announcement, etc.). Requires OAuth access token.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            shop_id: {
+              type: 'number',
+              description: 'Your shop ID',
+            },
+            title: {
+              type: 'string',
+              description: 'Shop title',
+            },
+            announcement: {
+              type: 'string',
+              description: 'Shop announcement message',
+            },
+            sale_message: {
+              type: 'string',
+              description: 'Message to buyers at checkout',
+            },
+            policy_welcome: {
+              type: 'string',
+              description: 'Shop policies welcome message',
+            },
+          },
+          required: ['shop_id'],
+        },
+        annotations: {
+          readOnlyHint: false,
+          destructiveHint: false,
+          idempotentHint: true,
+        },
+      },
+    ];
+  }
+
+  private async searchListings(args: any) {
+    const params: any = {
+      keywords: args.keywords,
+      limit: args.limit || 25,
+      offset: args.offset || 0,
+    };
+
+    if (args.min_price) params.min_price = args.min_price;
+    if (args.max_price) params.max_price = args.max_price;
+    if (args.sort_on) params.sort_on = args.sort_on;
+    if (args.sort_order) params.sort_order = args.sort_order;
+
+    const response = await this.axiosInstance.get('/application/listings/active', {
+      params,
+    });
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(response.data, null, 2),
+        },
+      ],
+    };
+  }
+
+  private async getListing(args: any) {
+    const includes = args.includes?.join(',');
+    const params = includes ? { includes } : {};
+
+    const response = await this.axiosInstance.get(
+      `/application/listings/${args.listing_id}`,
+      { params }
+    );
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(response.data, null, 2),
+        },
+      ],
+    };
+  }
+
+  private async getShop(args: any) {
+    const response = await this.axiosInstance.get(`/application/shops/${args.shop_id}`);
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(response.data, null, 2),
+        },
+      ],
+    };
+  }
+
+  private async getShopListings(args: any) {
+    const params = {
+      limit: args.limit || 25,
+      offset: args.offset || 0,
+      state: args.state || 'active',
+    };
+
+    const response = await this.axiosInstance.get(
+      `/application/shops/${args.shop_id}/listings`,
+      { params }
+    );
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(response.data, null, 2),
+        },
+      ],
+    };
+  }
+
+  private async searchShops(args: any) {
+    const params = {
+      shop_name: args.shop_name,
+      limit: args.limit || 25,
+      offset: args.offset || 0,
+    };
+
+    const response = await this.axiosInstance.get('/application/shops', { params });
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(response.data, null, 2),
+        },
+      ],
+    };
+  }
+
+  private async getListingInventory(args: any) {
+    const response = await this.axiosInstance.get(
+      `/application/listings/${args.listing_id}/inventory`
+    );
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(response.data, null, 2),
+        },
+      ],
+    };
+  }
+
+  private async getListingImages(args: any) {
+    const response = await this.axiosInstance.get(
+      `/application/listings/${args.listing_id}/images`
+    );
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(response.data, null, 2),
+        },
+      ],
+    };
+  }
+
+  private async getShopSections(args: any) {
+    const response = await this.axiosInstance.get(
+      `/application/shops/${args.shop_id}/sections`
+    );
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(response.data, null, 2),
+        },
+      ],
+    };
+  }
+
+  private async getTrendingListings(args: any) {
+    const params = {
+      limit: args.limit || 25,
+      offset: args.offset || 0,
+    };
+
+    const response = await this.axiosInstance.get('/application/listings/trending', {
+      params,
+    });
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(response.data, null, 2),
+        },
+      ],
+    };
+  }
+
+  private async findShops(args: any) {
+    const params: any = {
+      limit: args.limit || 25,
+      offset: args.offset || 0,
+    };
+
+    if (args.location) params.location = args.location;
+
+    const response = await this.axiosInstance.get('/application/shops', { params });
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(response.data, null, 2),
+        },
+      ],
+    };
+  }
+
+  // Shop Management Methods (require OAuth)
+  private async createListing(args: any) {
+    if (!this.config.accessToken) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(
+              {
+                error:
+                  'OAuth access token required. Set ETSY_ACCESS_TOKEN environment variable.',
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    }
+
+    const data: any = {
+      quantity: args.quantity,
+      title: args.title,
+      description: args.description,
+      price: args.price,
+      who_made: args.who_made,
+      when_made: args.when_made,
+      taxonomy_id: args.taxonomy_id,
+    };
+
+    if (args.shipping_profile_id) data.shipping_profile_id = args.shipping_profile_id;
+    if (args.shop_section_id) data.shop_section_id = args.shop_section_id;
+    if (args.tags) data.tags = args.tags;
+
+    const response = await this.axiosInstance.post(
+      `/application/shops/${args.shop_id}/listings`,
+      data
+    );
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(response.data, null, 2),
+        },
+      ],
+    };
+  }
+
+  private async updateListing(args: any) {
+    if (!this.config.accessToken) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(
+              {
+                error:
+                  'OAuth access token required. Set ETSY_ACCESS_TOKEN environment variable.',
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    }
+
+    const data: any = {};
+    if (args.title) data.title = args.title;
+    if (args.description) data.description = args.description;
+    if (args.price) data.price = args.price;
+    if (args.quantity) data.quantity = args.quantity;
+    if (args.tags) data.tags = args.tags;
+    if (args.shop_section_id !== undefined) data.shop_section_id = args.shop_section_id;
+
+    const response = await this.axiosInstance.patch(
+      `/application/shops/${args.shop_id}/listings/${args.listing_id}`,
+      data
+    );
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(response.data, null, 2),
+        },
+      ],
+    };
+  }
+
+  private async deleteListing(args: any) {
+    if (!this.config.accessToken) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(
+              {
+                error:
+                  'OAuth access token required. Set ETSY_ACCESS_TOKEN environment variable.',
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    }
+
+    const response = await this.axiosInstance.delete(
+      `/application/listings/${args.listing_id}`
+    );
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(
+            { success: true, message: 'Listing deleted successfully' },
+            null,
+            2
+          ),
+        },
+      ],
+    };
+  }
+
+  private async updateListingInventory(args: any) {
+    if (!this.config.accessToken) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(
+              {
+                error:
+                  'OAuth access token required. Set ETSY_ACCESS_TOKEN environment variable.',
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    }
+
+    const data: any = {
+      products: args.products,
+    };
+
+    if (args.price_on_property) data.price_on_property = args.price_on_property;
+    if (args.quantity_on_property) data.quantity_on_property = args.quantity_on_property;
+    if (args.sku_on_property) data.sku_on_property = args.sku_on_property;
+
+    const response = await this.axiosInstance.put(
+      `/application/listings/${args.listing_id}/inventory`,
+      data
+    );
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(response.data, null, 2),
+        },
+      ],
+    };
+  }
+
+  private async uploadListingImage(args: any) {
+    if (!this.config.accessToken) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(
+              {
+                error:
+                  'OAuth access token required. Set ETSY_ACCESS_TOKEN environment variable.',
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    }
+
+    // Note: Etsy API requires multipart/form-data for image upload
+    // This is a simplified version - actual implementation needs form-data handling
+    const data: any = {
+      image: args.image_url,
+    };
+
+    if (args.rank) data.rank = args.rank;
+    if (args.alt_text) data.alt_text = args.alt_text;
+
+    const response = await this.axiosInstance.post(
+      `/application/shops/${args.shop_id}/listings/${args.listing_id}/images`,
+      data
+    );
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(response.data, null, 2),
+        },
+      ],
+    };
+  }
+
+  private async createShopSection(args: any) {
+    if (!this.config.accessToken) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(
+              {
+                error:
+                  'OAuth access token required. Set ETSY_ACCESS_TOKEN environment variable.',
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    }
+
+    const response = await this.axiosInstance.post(
+      `/application/shops/${args.shop_id}/sections`,
+      { title: args.title }
+    );
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(response.data, null, 2),
+        },
+      ],
+    };
+  }
+
+  private async updateShopSection(args: any) {
+    if (!this.config.accessToken) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(
+              {
+                error:
+                  'OAuth access token required. Set ETSY_ACCESS_TOKEN environment variable.',
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    }
+
+    const response = await this.axiosInstance.put(
+      `/application/shops/${args.shop_id}/sections/${args.shop_section_id}`,
+      { title: args.title }
+    );
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(response.data, null, 2),
+        },
+      ],
+    };
+  }
+
+  private async deleteShopSection(args: any) {
+    if (!this.config.accessToken) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(
+              {
+                error:
+                  'OAuth access token required. Set ETSY_ACCESS_TOKEN environment variable.',
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    }
+
+    const response = await this.axiosInstance.delete(
+      `/application/shops/${args.shop_id}/sections/${args.shop_section_id}`
+    );
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(
+            { success: true, message: 'Shop section deleted successfully' },
+            null,
+            2
+          ),
+        },
+      ],
+    };
+  }
+
+  private async updateShop(args: any) {
+    if (!this.config.accessToken) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(
+              {
+                error:
+                  'OAuth access token required. Set ETSY_ACCESS_TOKEN environment variable.',
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    }
+
+    const data: any = {};
+    if (args.title) data.title = args.title;
+    if (args.announcement) data.announcement = args.announcement;
+    if (args.sale_message) data.sale_message = args.sale_message;
+    if (args.policy_welcome) data.policy_welcome = args.policy_welcome;
+
+    const response = await this.axiosInstance.put(
+      `/application/shops/${args.shop_id}`,
+      data
+    );
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(response.data, null, 2),
+        },
+      ],
+    };
+  }
+
+  // Prompts functionality
+  private getPrompts(): Prompt[] {
+    return [
+      {
+        name: 'create-listing-guide',
+        title: 'Create Listing Guide',
+        description: 'Guide for creating a complete Etsy listing with best practices',
+        arguments: [
+          {
+            name: 'product_type',
+            description: 'Type of product to list (e.g., handmade, vintage, craft supply)',
+            required: true,
+          },
+        ],
+      },
+      {
+        name: 'optimize-listing',
+        title: 'Optimize Listing',
+        description: 'Generate SEO-optimized title, tags, and description for a listing',
+        arguments: [
+          {
+            name: 'listing_id',
+            description: 'The ID of the listing to optimize',
+            required: true,
+          },
+          {
+            name: 'focus_keywords',
+            description: 'Keywords to focus on for SEO',
+            required: false,
+          },
+        ],
+      },
+      {
+        name: 'shop-analytics-review',
+        title: 'Shop Analytics Review',
+        description: 'Create a comprehensive shop performance review template',
+        arguments: [
+          {
+            name: 'shop_id',
+            description: 'The shop ID to analyze',
+            required: true,
+          },
+          {
+            name: 'time_period',
+            description: 'Time period for analysis (e.g., last_month, last_quarter)',
+            required: false,
+          },
+        ],
+      },
+      {
+        name: 'product-photography-tips',
+        title: 'Product Photography Tips',
+        description: 'Get tailored product photography guidance for Etsy',
+        arguments: [
+          {
+            name: 'product_category',
+            description: 'Category of product (e.g., jewelry, home decor, clothing)',
+            required: true,
+          },
+        ],
+      },
+      {
+        name: 'pricing-strategy',
+        title: 'Pricing Strategy',
+        description: 'Calculate competitive pricing for Etsy listings',
+        arguments: [
+          {
+            name: 'material_cost',
+            description: 'Total cost of materials',
+            required: true,
+          },
+          {
+            name: 'time_hours',
+            description: 'Hours spent creating the product',
+            required: true,
+          },
+          {
+            name: 'desired_hourly_rate',
+            description: 'Desired hourly rate for labor',
+            required: false,
+          },
+        ],
+      },
+    ];
+  }
+
+  private async getPrompt(name: string, args?: Record<string, string>): Promise<GetPromptResult> {
+    switch (name) {
+      case 'create-listing-guide':
+        return {
+          messages: [
+            {
+              role: 'user',
+              content: {
+                type: 'text',
+                text: `Help me create a compelling Etsy listing for a ${args?.product_type || 'handmade'} product. Please guide me through:
+
+1. **Title Creation** (max 140 characters):
+   - Include key search terms
+   - Be specific and descriptive
+   - Follow format: [What it is] | [Key feature] | [Use case]
+
+2. **Description Structure**:
+   - Opening hook (2-3 sentences)
+   - Key features and benefits (bullet points)
+   - Materials and dimensions
+   - Care instructions
+   - Shipping and policies
+
+3. **Tags Strategy** (13 tags):
+   - Mix of broad and specific terms
+   - Include long-tail keywords
+   - Consider seasonal trends
+
+4. **Pricing Considerations**:
+   - Material costs + labor + overhead
+   - Competitive analysis
+   - Etsy fees (6.5% transaction + 3% + $0.25 processing)
+
+5. **Photos Checklist**:
+   - Main photo: white background, product centered
+   - Lifestyle photos showing scale/use
+   - Detail shots of craftsmanship
+   - Size comparison images
+
+Please help me optimize each section for maximum visibility and conversions.`,
+              },
+            },
+          ],
+        };
+
+      case 'optimize-listing':
+        const listingId = args?.listing_id;
+        const keywords = args?.focus_keywords || 'handmade, unique, quality';
+        
+        return {
+          messages: [
+            {
+              role: 'user',
+              content: {
+                type: 'text',
+                text: `Analyze and optimize Etsy listing ${listingId} with focus on these keywords: ${keywords}
+
+Please provide:
+
+1. **SEO-Optimized Title**:
+   - Incorporate keywords: ${keywords}
+   - Stay under 140 characters
+   - Front-load important terms
+
+2. **Enhanced Description**:
+   - Keyword-rich opening paragraph
+   - Scannable bullet points
+   - Answer common customer questions
+   - Include size, material, and shipping info
+
+3. **Strategic Tags** (13 recommendations):
+   - High-volume search terms
+   - Niche-specific keywords
+   - Long-tail variations
+   - Seasonal opportunities
+
+4. **Competitive Analysis**:
+   - Similar listings comparison
+   - Price positioning
+   - Unique selling points
+
+5. **Action Items**:
+   - Quick wins for immediate improvement
+   - Long-term optimization strategies
+   - A/B testing suggestions`,
+              },
+            },
+          ],
+        };
+
+      case 'shop-analytics-review':
+        const shopId = args?.shop_id;
+        const period = args?.time_period || 'last_month';
+        
+        return {
+          messages: [
+            {
+              role: 'user',
+              content: {
+                type: 'text',
+                text: `Create a comprehensive analytics review for Etsy shop ${shopId} covering ${period}.
+
+Analysis Framework:
+
+1. **Traffic Metrics**:
+   - Total visits and sources
+   - Conversion rate trends
+   - Bounce rate analysis
+   - Top-performing listings
+
+2. **Sales Performance**:
+   - Revenue and order volume
+   - Average order value
+   - Best-selling products
+   - Seasonal patterns
+
+3. **SEO Performance**:
+   - Top search terms driving traffic
+   - Listing ranking improvements/declines
+   - Click-through rates
+   - Tag effectiveness
+
+4. **Customer Insights**:
+   - Geographic distribution
+   - Repeat customer rate
+   - Review sentiment analysis
+   - Cart abandonment rate
+
+5. **Recommendations**:
+   - Underperforming listings to optimize
+   - Inventory adjustments
+   - Marketing opportunities
+   - Pricing strategy review
+
+Please use the available MCP tools to gather data and provide actionable insights.`,
+              },
+            },
+          ],
+        };
+
+      case 'product-photography-tips':
+        const category = args?.product_category || 'general products';
+        
+        return {
+          messages: [
+            {
+              role: 'user',
+              content: {
+                type: 'text',
+                text: `Provide comprehensive product photography guidance for ${category} on Etsy.
+
+**Photography Essentials:**
+
+1. **Equipment Setup**:
+   - Camera: DSLR, mirrorless, or modern smartphone
+   - Lighting: Natural light or softbox setup
+   - Background: White sweep or lifestyle setting
+   - Tripod for consistency
+
+2. **Shot List for ${category}**:
+   - Hero shot (main listing photo)
+   - Scale/size reference shots
+   - Detail and texture closeups
+   - Lifestyle/in-use photos
+   - Packaging presentation
+   - Multiple angles (360° view)
+
+3. **Technical Requirements**:
+   - Resolution: Minimum 2000px on longest side
+   - Format: JPG for best compatibility
+   - File size: Under 1MB for fast loading
+   - Aspect ratio: Square (1:1) works best
+
+4. **Styling Tips for ${category}**:
+   - Props that complement without distracting
+   - Consistent brand aesthetic
+   - Color harmony and contrast
+   - Storytelling through composition
+
+5. **Post-Processing**:
+   - Brightness and contrast adjustment
+   - Color correction for accuracy
+   - Background cleanup
+   - Watermarking considerations
+
+6. **Etsy-Specific Best Practices**:
+   - First photo determines thumbnail
+   - Mobile optimization crucial (70% of traffic)
+   - Use all 10 image slots
+   - Video recommended for engagement`,
+              },
+            },
+          ],
+        };
+
+      case 'pricing-strategy':
+        const materialCost = parseFloat(args?.material_cost || '0');
+        const timeHours = parseFloat(args?.time_hours || '0');
+        const hourlyRate = parseFloat(args?.desired_hourly_rate || '25');
+        
+        const laborCost = timeHours * hourlyRate;
+        const subtotal = materialCost + laborCost;
+        const overhead = subtotal * 0.15; // 15% overhead
+        const totalCost = subtotal + overhead;
+        const etsyFees = totalCost * 0.095; // 6.5% transaction + ~3% processing
+        const minimumPrice = totalCost + etsyFees;
+        const suggestedRetail = minimumPrice * 1.5; // 50% profit margin
+        
+        return {
+          messages: [
+            {
+              role: 'user',
+              content: {
+                type: 'text',
+                text: `Pricing Analysis for Your Etsy Product:
+
+**Cost Breakdown:**
+- Materials: $${materialCost.toFixed(2)}
+- Labor (${timeHours}h × $${hourlyRate}/h): $${laborCost.toFixed(2)}
+- Overhead (15%): $${overhead.toFixed(2)}
+- **Total Cost: $${totalCost.toFixed(2)}**
+
+**Etsy Fees:**
+- Transaction fee (6.5%): $${(totalCost * 0.065).toFixed(2)}
+- Processing fee (~3%): $${(totalCost * 0.03).toFixed(2)}
+- Listing fee: $0.20
+- **Total Fees: $${(etsyFees + 0.20).toFixed(2)}**
+
+**Pricing Recommendations:**
+
+1. **Break-Even Price:** $${minimumPrice.toFixed(2)}
+   - Covers all costs and fees
+   - No profit margin
+
+2. **Suggested Retail Price:** $${suggestedRetail.toFixed(2)}
+   - Includes 50% profit margin
+   - Competitive positioning
+   - Room for sales/promotions
+
+3. **Premium Positioning:** $${(suggestedRetail * 1.3).toFixed(2)}
+   - Higher perceived value
+   - Artisan/luxury market
+   - Custom/made-to-order
+
+**Pricing Strategy Tips:**
+
+• **Psychological Pricing:** Consider ending prices in .95 or .99
+• **Competitor Analysis:** Research 10-15 similar listings
+• **Volume Discounts:** Offer tiered pricing for multiple purchases
+• **Seasonal Adjustments:** Premium during peak seasons
+• **Bundle Opportunities:** Create product sets for higher AOV
+
+**Profitability Check:**
+- At $${suggestedRetail.toFixed(2)}: ${((suggestedRetail - minimumPrice) / suggestedRetail * 100).toFixed(1)}% profit margin
+- Monthly goal: Sell 20 units = $${(suggestedRetail * 20).toFixed(2)} revenue
+- Profit: $${((suggestedRetail - minimumPrice) * 20).toFixed(2)}
+
+Would you like me to analyze competitor pricing or explore different pricing strategies?`,
+              },
+            },
+          ],
+        };
+
+      default:
+        throw new Error(`Unknown prompt: ${name}`);
+    }
+  }
+
+  // Resources functionality
+  private getResources(): Resource[] {
+    return [
+      {
+        name: 'etsy-api-docs',
+        uri: 'etsy://docs/api',
+        title: 'Etsy API Documentation',
+        description: 'Comprehensive Etsy Open API v3 documentation and reference',
+        mimeType: 'text/plain',
+      },
+      {
+        name: 'etsy-seller-handbook',
+        uri: 'etsy://docs/seller-handbook',
+        title: 'Etsy Seller Handbook',
+        description: 'Best practices and guides for Etsy sellers',
+        mimeType: 'text/plain',
+      },
+      {
+        name: 'etsy-seo-guide',
+        uri: 'etsy://docs/seo-guide',
+        title: 'Etsy SEO Guide',
+        description: 'Complete guide to Etsy search engine optimization',
+        mimeType: 'text/plain',
+      },
+      {
+        name: 'etsy-shipping-guide',
+        uri: 'etsy://docs/shipping',
+        title: 'Etsy Shipping Guide',
+        description: 'Shipping policies, strategies, and best practices',
+        mimeType: 'text/plain',
+      },
+      {
+        name: 'etsy-photography-tips',
+        uri: 'etsy://docs/photography',
+        title: 'Product Photography Tips',
+        description: 'Professional product photography guide for Etsy',
+        mimeType: 'text/plain',
+      },
+      {
+        name: 'etsy-fees-calculator',
+        uri: 'etsy://tools/fees-calculator',
+        title: 'Etsy Fees Calculator',
+        description: 'Calculate all Etsy fees and pricing recommendations',
+        mimeType: 'application/json',
+      },
+    ];
+  }
+
+  private async readResource(uri: string): Promise<ReadResourceResult> {
+    switch (uri) {
+      case 'etsy://docs/api':
+        return {
+          contents: [
+            {
+              uri,
+              mimeType: 'text/plain',
+              text: `# Etsy Open API v3 Documentation
+
+**Base URL:** https://openapi.etsy.com/v3
+
+## Authentication
+- **API Key:** Required for all requests (x-api-key header)
+- **OAuth 2.0:** Required for write operations and private data
+
+## Rate Limits
+- 10,000 requests per day per API key
+- Burst limit: 10 requests per second
+
+## Key Endpoints
+
+### Listings
+- GET /v3/application/listings/active - Search active listings
+- GET /v3/application/listings/{listing_id} - Get listing details
+- POST /v3/application/shops/{shop_id}/listings - Create listing (OAuth)
+- PUT /v3/application/shops/{shop_id}/listings/{listing_id} - Update listing (OAuth)
+
+### Shops
+- GET /v3/application/shops/{shop_id} - Get shop details
+- GET /v3/application/shops/{shop_id}/listings/active - Get shop listings
+- PATCH /v3/application/shops/{shop_id} - Update shop (OAuth)
+
+### Search
+- GET /v3/application/listings/active - Search with filters
+- GET /v3/application/shops - Search shops
+
+## Common Parameters
+- **limit:** Number of results (max 100)
+- **offset:** Pagination offset
+- **keywords:** Search terms
+- **sort_on:** created, price, score
+- **sort_order:** asc, desc
+
+## Response Format
+All responses return JSON with consistent structure:
+{
+  "count": 10,
+  "results": [...],
+  "next_page": "..."
+}
+
+## Error Codes
+- 400: Bad Request
+- 401: Unauthorized
+- 403: Forbidden
+- 404: Not Found
+- 429: Rate Limit Exceeded
+- 500: Internal Server Error
+
+For complete documentation, visit: https://developers.etsy.com/documentation`,
+            },
+          ],
+        };
+
+      case 'etsy://docs/seller-handbook':
+        return {
+          contents: [
+            {
+              uri,
+              mimeType: 'text/plain',
+              text: `# Etsy Seller Handbook
+
+## Getting Started
+
+### Shop Setup
+1. Create your shop name (unique, memorable, brandable)
+2. Set shop policies (returns, exchanges, privacy)
+3. Configure payment methods
+4. Set up shipping profiles
+5. Add shop sections for organization
+
+### Listing Optimization
+- **Title:** 140 characters, front-load keywords
+- **Tags:** 13 tags, mix broad and specific terms
+- **Description:** Rich details, answer questions
+- **Photos:** 10 images, high quality, multiple angles
+- **Price:** Competitive but profitable
+
+## Best Practices
+
+### Product Photography
+- Natural lighting or softbox setup
+- White/neutral background for main image
+- Lifestyle photos showing scale and use
+- Detail shots of craftsmanship
+- Consistent style across listings
+
+### SEO Strategy
+- Research keywords with Etsy search
+- Use all 13 tag slots
+- Update titles seasonally
+- Monitor search analytics
+- Optimize based on performance
+
+### Customer Service
+- Respond within 24 hours
+- Be professional and friendly
+- Address issues promptly
+- Request reviews politely
+- Build relationships
+
+### Marketing
+- Share listings on social media
+- Use Etsy Ads strategically
+- Offer promotions and sales
+- Build email list
+- Collaborate with other sellers
+
+### Shop Management
+- Update inventory regularly
+- Process orders promptly
+- Track metrics and analytics
+- Adjust strategy based on data
+- Stay current with Etsy policies
+
+## Growth Strategies
+
+### Scaling Your Business
+1. Identify best-sellers
+2. Create complementary products
+3. Optimize production workflow
+4. Consider help or automation
+5. Expand product line strategically
+
+### Seasonal Planning
+- Plan inventory 3 months ahead
+- Create seasonal listings early
+- Adjust keywords for holidays
+- Run strategic promotions
+- Prepare for peak shipping times
+
+## Resources
+- Etsy Seller Handbook: https://www.etsy.com/seller-handbook
+- Etsy Forums: Community support
+- Etsy Teams: Local seller groups
+- Etsy Success Newsletter: Tips and updates`,
+            },
+          ],
+        };
+
+      case 'etsy://docs/seo-guide':
+        return {
+          contents: [
+            {
+              uri,
+              mimeType: 'text/plain',
+              text: `# Complete Etsy SEO Guide
+
+## Understanding Etsy Search
+
+Etsy search algorithm considers:
+1. **Query Matching:** Titles, tags, categories, attributes
+2. **Listing Quality Score:** Photos, description, shop policies
+3. **Customer Experience:** Reviews, shipping, messages
+4. **Shop History:** Sales, favorites, age
+
+## Keyword Research
+
+### Tools and Methods
+- Etsy search bar autocomplete
+- Competitor listing analysis
+- Google Trends for seasonal terms
+- Customer language from reviews
+- Long-tail keyword variations
+
+### Keyword Types
+- **Broad terms:** "handmade jewelry"
+- **Specific terms:** "sterling silver moon necklace"
+- **Long-tail:** "personalized graduation gift for daughter"
+- **Seasonal:** "Christmas stocking stuffer"
+
+## Title Optimization
+
+### Best Practices
+- **Front-load keywords:** Most important words first
+- **Be specific:** "Vintage 1960s Leather Crossbody Bag"
+- **Include key attributes:** Size, color, material, use
+- **Use natural language:** Readable, not keyword stuffed
+- **Stay under 140 characters**
+
+### Title Formula
+[What It Is] | [Key Features] | [Use Case/Benefit]
+
+Example: "Handmade Ceramic Mug | 16oz Large Coffee Cup | Perfect Gift for Coffee Lovers"
+
+## Tag Strategy
+
+### Maximizing 13 Tags
+- 3-4 broad terms (handmade jewelry)
+- 4-5 specific terms (moonstone pendant necklace)
+- 3-4 long-tail keywords (boho wedding jewelry gift)
+- 1-2 seasonal/trending terms
+
+### Tag Tips
+- Use all 13 tags
+- Multi-word phrases (etsy treats as one tag)
+- Consider misspellings for common terms
+- Update seasonally
+- Test and adjust based on analytics
+
+## Description SEO
+
+### Structure
+1. **Opening paragraph:** Keyword-rich summary (first 160 characters show in search)
+2. **Key features:** Bullet points with natural keywords
+3. **Details:** Size, materials, care instructions
+4. **Story/Use cases:** Emotional connection
+5. **Policies:** Shipping, returns (reassurance)
+
+### SEO Writing Tips
+- Natural keyword integration
+- Answer common questions
+- Use headers/formatting
+- Include relevant attributes
+- Cross-link related listings
+
+## Categories and Attributes
+
+### Importance
+- Required for category-specific searches
+- Helps Etsy understand your product
+- Affects search placement
+
+### Best Practices
+- Choose most specific category
+- Fill all relevant attributes
+- Be accurate (affects trust signals)
+- Update when Etsy adds new options
+
+## Shop-Wide SEO
+
+### Shop Title
+- Appears in external search (Google)
+- Include main product category
+- Keep under 55 characters
+
+### Shop Sections
+- Organize products logically
+- Use keyword-rich section names
+- Helps customers browse
+- Improves internal linking
+
+### About Section
+- Tell your brand story
+- Include relevant keywords naturally
+- Build trust and connection
+
+## Performance Tracking
+
+### Key Metrics
+- **Search views:** How often listings appear
+- **Click-through rate:** Views vs. visits
+- **Conversion rate:** Visits to sales
+- **Search terms:** What brings traffic
+
+### Tools
+- Etsy Stats (Shop Manager)
+- Google Analytics (external traffic)
+- Search Analytics (keyword performance)
+
+## Advanced Strategies
+
+### A/B Testing
+- Test title variations
+- Try different primary photos
+- Adjust pricing strategies
+- Monitor conversion impact
+
+### Seasonal Optimization
+- Update keywords 6-8 weeks before holidays
+- Create seasonal landing collections
+- Adjust inventory for demand
+- Plan content calendar
+
+### External SEO
+- Social media sharing
+- Blog content
+- Pinterest optimization
+- Backlink building
+
+## Common SEO Mistakes
+
+### Avoid These
+- ❌ Keyword stuffing (unreadable titles)
+- ❌ Irrelevant tags (misleading)
+- ❌ All caps titles (looks spammy)
+- ❌ Trademark violations
+- ❌ Duplicate listings (compete with yourself)
+- ❌ Ignoring analytics (data-driven decisions)
+
+## Quick Wins Checklist
+
+1. ✅ Use all 13 tags on every listing
+2. ✅ Front-load titles with keywords
+3. ✅ Fill all category attributes
+4. ✅ Add 10 high-quality photos
+5. ✅ Write detailed descriptions
+6. ✅ Update seasonal listings early
+7. ✅ Monitor and adjust based on stats
+8. ✅ Respond to messages quickly
+9. ✅ Encourage reviews
+10. ✅ Keep inventory active
+
+Remember: SEO is ongoing. Review and optimize regularly based on performance data.`,
+            },
+          ],
+        };
+
+      case 'etsy://docs/shipping':
+        return {
+          contents: [
+            {
+              uri,
+              mimeType: 'text/plain',
+              text: `# Etsy Shipping Guide
+
+## Shipping Strategy
+
+### Setting Up Profiles
+- Create profiles for different product types
+- Include domestic and international options
+- Consider package dimensions and weight
+- Build in handling time realistically
+
+### Pricing Models
+1. **Calculated shipping:** Real-time carrier rates
+2. **Fixed shipping:** Set price per location
+3. **Free shipping:** Built into product price
+4. **Combined shipping:** Discounts for multiple items
+
+## Domestic Shipping (US)
+
+### Carrier Options
+- **USPS:** Most cost-effective for small items
+  - First Class: Under 16oz, 2-5 days
+  - Priority Mail: 1-3 days, includes tracking
+  - Priority Express: Overnight
+- **UPS/FedEx:** Better for heavy items
+- **Regional carriers:** For local deliveries
+
+### Shipping Supplies
+- Proper boxes/mailers for protection
+- Bubble wrap or packing peanuts
+- Thank you cards/branding materials
+- Shipping labels (consider label printer)
+- Tape gun for efficiency
+
+## International Shipping
+
+### Considerations
+- Customs forms required
+- Longer delivery times (7-21+ days)
+- Higher costs
+- Customs fees (buyer responsibility)
+- Tracking may be limited
+
+### International Best Practices
+- Clearly state delivery times
+- Mention customs fees in listing
+- Use USPS International services
+- Consider restricted countries
+- Package securely for long transit
+
+## Free Shipping
+
+### Etsy Free Shipping Guarantee
+- US orders $35+
+- Boosts search placement
+- Competitive advantage
+
+### Implementation Strategies
+1. **Built-in pricing:** Add shipping to product cost
+2. **Threshold:** Free over $X
+3. **Flat rate:** Same price all items
+4. **Promotional:** Limited time offers
+
+### Making It Work
+- Calculate average shipping cost
+- Adjust product pricing accordingly
+- Monitor profit margins
+- Test different thresholds
+
+## Processing and Handling
+
+### Handling Time
+- Set realistic timeframes
+- Account for production time
+- Consider weekends/holidays
+- Update for busy seasons
+- Communicate delays promptly
+
+### Best Practices
+- Process orders within 24 hours
+- Print labels via Etsy (discounts)
+- Upload tracking immediately
+- Send shipped notification
+- Include tracking in message
+
+## Packaging Tips
+
+### Protection
+- Double box fragile items
+- Use adequate cushioning
+- Seal securely with quality tape
+- Waterproof if necessary
+- Test drop to ensure safety
+
+### Branding
+- Thank you card with logo
+- Branded tissue paper/tape
+- Business cards for reorders
+- Care instruction cards
+- Surprise bonus (sticker, sample)
+
+### Sustainability
+- Eco-friendly materials
+- Minimal packaging (reduce waste)
+- Recyclable/biodegradable options
+- Reuse shipping materials
+- Communicate green practices
+
+## Tracking and Insurance
+
+### Tracking
+- Always include for $20+ orders
+- Protects buyer and seller
+- Required for claims
+- Builds customer confidence
+- Enables delivery confirmation
+
+### Insurance
+- Recommend for $100+ items
+- Protects against loss/damage
+- Small additional cost
+- Peace of mind for both parties
+- Required for high-value claims
+
+## Handling Shipping Issues
+
+### Lost Packages
+1. Check tracking for updates
+2. Contact carrier after expected delivery
+3. File claim if insured
+4. Reship or refund customer
+5. Document everything
+
+### Damaged Items
+1. Request photos from customer
+2. File carrier claim if insured
+3. Offer replacement or refund
+4. Improve packaging for future
+5. Learn from issues
+
+### Delays
+- Communicate proactively
+- Provide tracking updates
+- Apologize sincerely
+- Offer solutions (expedited reship)
+- Learn from experience
+
+## International Customs
+
+### Required Information
+- Accurate item description
+- Value for customs
+- Country of origin
+- HS tariff code (when applicable)
+- Proper forms (CN22, CN23)
+
+### Common Issues
+- Held in customs (varies by country)
+- Duties/taxes (buyer pays)
+- Restricted items (varies by country)
+- Lost customs forms
+
+## Shipping Metrics to Track
+
+### Key Performance Indicators
+- Average shipping cost per order
+- Delivery time vs. promised time
+- Damage/loss rate
+- Customer satisfaction with shipping
+- Carrier performance
+
+### Optimization
+- Compare carrier rates regularly
+- Negotiate volume discounts
+- Optimize package sizes
+- Reduce handling time
+- Improve packaging efficiency
+
+## Seasonal Shipping
+
+### Holiday Preparation
+- Post cutoff dates clearly
+- Allow extra processing time
+- Recommend shipping upgrades
+- Communicate delays promptly
+- Set shop vacation if overwhelmed
+
+### Peak Season Tips
+- Order supplies early
+- Batch process orders
+- Use shipping software
+- Consider hired help
+- Maintain quality standards
+
+## Shipping Policies
+
+### What to Include
+- Processing/handling time
+- Shipping methods available
+- International shipping details
+- Customs/duties information
+- Lost package procedures
+- Upgrade options
+
+### Communication
+- Clear in listing descriptions
+- Shop policies page
+- Order messages
+- FAQ section
+- Proactive updates
+
+Remember: Excellent shipping experience leads to 5-star reviews and repeat customers!`,
+            },
+          ],
+        };
+
+      case 'etsy://docs/photography':
+        return {
+          contents: [
+            {
+              uri,
+              mimeType: 'text/plain',
+              text: `# Professional Product Photography for Etsy
+
+## Equipment Essentials
+
+### Camera Options
+- **DSLR/Mirrorless:** Best quality and control
+- **High-end smartphone:** Adequate for many products
+- **Point-and-shoot:** Budget-friendly option
+
+### Lighting
+- **Natural light:** Free, beautiful (near window)
+- **Softbox kit:** $50-200, consistent results
+- **Ring light:** Great for small items
+- **Reflectors:** Bounce and fill light ($20-40)
+
+### Support Equipment
+- **Tripod:** Essential for consistency ($30-100)
+- **Backdrop:** White seamless paper or sweep
+- **Light tent:** For small items ($20-50)
+- **Props:** Lifestyle and scale reference
+
+## Photo Requirements
+
+### Technical Specifications
+- **Resolution:** Minimum 2000px longest side
+- **Format:** JPG preferred
+- **File size:** Under 1MB for fast loading
+- **Aspect ratio:** Square (1:1) ideal
+- **Number:** Use all 10 slots
+
+### Etsy-Specific Considerations
+- First photo is thumbnail (most important)
+- Mobile optimization critical (70% traffic)
+- Photos appear in search results
+- Zoom feature requires high resolution
+
+## The Essential Shot List
+
+### 1. Hero Shot (Main Photo)
+- Clean white/neutral background
+- Product centered and well-lit
+- Shows full item clearly
+- No distractions
+- **This determines clicks!**
+
+### 2. Detail Shots (2-3 photos)
+- Close-ups of craftsmanship
+- Texture and materials
+- Quality indicators
+- Unique features
+- Proof of handmade quality
+
+### 3. Scale Reference (1-2 photos)
+- Product in hand
+- Next to common object (coin, ruler)
+- Lifestyle shot showing size
+- Multiple items together
+
+### 4. Lifestyle Photos (2-3 photos)
+- Product in use
+- Styled in environment
+- Emotional connection
+- Shows practical application
+- Aspirational yet relatable
+
+### 5. Variations (if applicable)
+- Color options
+- Size options
+- Customization examples
+- Before/after (if relevant)
+
+### 6. Packaging Shot (1 photo)
+- How it arrives
+- Gift-ready presentation
+- Professional impression
+- Sets expectations
+
+## Lighting Techniques
+
+### Natural Light Setup
+1. **Location:** Near large window
+2. **Time:** Overcast day or indirect sunlight
+3. **Positioning:** Product 3-5 feet from window
+4. **Fill light:** White reflector opposite window
+5. **Background:** Window to side, not behind
+
+### Artificial Light Setup
+1. **Main light:** 45° angle, above product
+2. **Fill light:** Opposite side, lower intensity
+3. **Background light:** Optional, separates product
+4. **Diffusion:** Soften with umbrella or softbox
+
+### Common Lighting Mistakes
+- ❌ Direct harsh sunlight (hard shadows)
+- ❌ Yellow indoor bulbs (color cast)
+- ❌ Mixed light sources (inconsistent color)
+- ❌ Underexposure (dark, details lost)
+- ❌ Overexposure (blown highlights)
+
+## Styling and Composition
+
+### Rule of Thirds
+- Divide frame into 3x3 grid
+- Place subject at intersections
+- Creates visual interest
+- More dynamic than centered
+
+### Background Choices
+- **White:** Clean, professional, versatile
+- **Neutral (gray, beige):** Sophisticated
+- **Wood/texture:** Warm, handmade feel
+- **Lifestyle setting:** Context and story
+- **Avoid:** Busy patterns, competing colors
+
+### Props and Styling
+- **Purpose:** Complement, not compete
+- **Scale:** Show size and context
+- **Color:** Harmonize with product
+- **Relevance:** Support product story
+- **Minimalism:** Less is often more
+
+## Camera Settings
+
+### Smartphone Photography
+- **HDR Mode:** ON for balanced exposure
+- **Grid:** Enable for composition
+- **Focus:** Tap to focus on product
+- **Exposure:** Adjust with slider
+- **Portrait Mode:** Use for depth (carefully)
+
+### DSLR/Mirrorless Settings
+- **Aperture:** f/8-f/16 for sharpness
+- **ISO:** 100-400 (minimize noise)
+- **Shutter speed:** 1/125 or faster
+- **White balance:** Match light source
+- **Shooting mode:** Aperture priority or manual
+
+## Post-Processing
+
+### Essential Edits
+1. **Crop:** Straighten and compose
+2. **Exposure:** Brighten if needed
+3. **White balance:** Correct color cast
+4. **Contrast:** Add depth
+5. **Sharpen:** Enhance details (subtle)
+
+### Editing Software
+- **Mobile:** Snapseed, VSCO, Lightroom Mobile
+- **Desktop:** Adobe Lightroom, Photoshop
+- **Free:** GIMP, Photopea
+- **Etsy App:** Basic editing built-in
+
+### Consistency is Key
+- Create presets for brand look
+- Edit entire shoot together
+- Match lighting across images
+- Maintain color accuracy
+- Same background style
+
+## Category-Specific Tips
+
+### Jewelry
+- Macro lens or smartphone macro mode
+- Neutral background or lifestyle
+- Show scale (worn on model)
+- Capture sparkle and detail
+- Multiple angles of stones
+
+### Clothing
+- On model or dress form
+- Show fit and drape
+- Detail shots of fabric/stitching
+- Size chart reference
+- Flat lay for patterns
+
+### Home Decor
+- Staged in room setting
+- Show scale with furniture
+- Multiple room applications
+- Detail shots of materials
+- Lighting effects if applicable
+
+### Art/Prints
+- Straight-on, no distortion
+- Frame it to show presentation
+- Include size reference
+- Detail shot if textured
+- Lifestyle shot on wall
+
+## Mobile Photography Tips
+
+### Smartphone Best Practices
+- Clean lens before shooting
+- Use built-in grid lines
+- Tap to focus on product
+- Shoot in natural light
+- Use HDR mode
+- Take multiple shots
+- Edit consistently
+
+### Mobile Limitations
+- Lower resolution than DSLR
+- Less control over depth of field
+- Challenging in low light
+- Limited zoom (use digital carefully)
+
+## Video Content
+
+### Why Add Video
+- 360° product view
+- Show size and scale
+- Demonstrate use
+- Increase engagement
+- Boost conversions
+
+### Video Tips
+- 5-15 seconds ideal
+- Stable (use tripod)
+- Good lighting
+- Slow smooth movements
+- No sound needed
+- Show key features
+
+## Photo Mistakes to Avoid
+
+### Common Errors
+- ❌ Cluttered background
+- ❌ Poor lighting (dark/yellow)
+- ❌ Blurry images
+- ❌ Incorrect colors
+- ❌ Can't see details
+- ❌ Inconsistent style
+- ❌ Filter overuse
+- ❌ Watermarks (reduces clicks)
+
+## Workflow Efficiency
+
+### Batch Photography
+1. Set up once for multiple products
+2. Same lighting for consistency
+3. Shoot all variations
+4. Edit together with presets
+5. Upload in batch
+
+### Time-Saving Tips
+- Prepare all products beforehand
+- Set up permanent photo station
+- Use presets for editing
+- Create shot list template
+- Schedule regular photo days
+
+## Testing and Optimization
+
+### A/B Testing
+- Try different main photos
+- Test lifestyle vs. white background
+- Monitor click-through rates
+- Adjust based on performance
+
+### Analytics
+- Track which photos get clicked
+- Monitor conversion rates
+- Note customer questions about photos
+- Update based on data
+
+Remember: Photos are your most important listing element. Invest time in getting them right!`,
+            },
+          ],
+        };
+
+      case 'etsy://tools/fees-calculator':
+        return {
+          contents: [
+            {
+              uri,
+              mimeType: 'application/json',
+              text: JSON.stringify({
+                title: 'Etsy Fees Calculator',
+                description: 'Calculate all Etsy fees and determine optimal pricing',
+                fees: {
+                  listing_fee: 0.20,
+                  transaction_fee_percent: 6.5,
+                  payment_processing_percent: 3.0,
+                  payment_processing_fixed: 0.25,
+                  offsite_ads_percent: 12.0, // for sales under $10k/year
+                  currency_conversion_percent: 2.5,
+                },
+                calculator: {
+                  example: {
+                    product_price: 50.00,
+                    calculation: {
+                      listing_fee: 0.20,
+                      transaction_fee: 3.25, // 6.5% of $50
+                      payment_processing: 1.75, // 3% of $50 + $0.25
+                      total_fees: 5.20,
+                      seller_receives: 44.80,
+                      fee_percentage: 10.4,
+                    },
+                  },
+                },
+                pricing_formula: {
+                  minimum_price: '(Material_Cost + Labor_Cost + Overhead) / (1 - Fee_Percentage)',
+                  suggested_retail: 'Minimum_Price * (1 + Desired_Profit_Margin)',
+                  profit_margin: 'Recommended 30-50% for sustainable business',
+                },
+                tips: [
+                  'Build fees into your pricing, don\'t absorb them',
+                  'Account for 10-15% in fees for domestic sales',
+                  'Add 15-20% for international sales (currency conversion)',
+                  'Remember offsite ads are 12% (15% if over $10k annual)',
+                  'Free shipping? Add average shipping cost to price',
+                  'Consider payment processor fees vary by country',
+                ],
+              }, null, 2),
+            },
+          ],
+        };
+
+      default:
+        throw new Error(`Unknown resource URI: ${uri}`);
+    }
+  }
+
+  getServer(): Server {
+    return this.server;
+  }
+
+  async run(): Promise<void> {
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+    console.error('Etsy MCP Server running on stdio');
+  }
+}
+
+// Smithery createServer export (required for Smithery deployment)
+export default function createServer({ config }: { config?: z.infer<typeof configSchema> }) {
+  const etsyConfig: EtsyConfig = {
+    apiKey: config?.apiKey || process.env.ETSY_API_KEY || 'demo-key-readonly',
+    shopId: config?.shopId || process.env.ETSY_SHOP_ID,
+    accessToken: config?.accessToken || process.env.ETSY_ACCESS_TOKEN,
+  };
+
+  // No validation - server can run without credentials for demo/documentation purposes
+  // API calls will fail gracefully if credentials are missing
+
+  const mcpServer = new EtsyMCPServer(etsyConfig);
+  return mcpServer.getServer();
+}
+
+// CLI entry point (for direct execution with stdio)
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const config: EtsyConfig = {
+    apiKey: process.env.ETSY_API_KEY || '',
+    shopId: process.env.ETSY_SHOP_ID,
+    accessToken: process.env.ETSY_ACCESS_TOKEN,
+  };
+
+  if (!config.apiKey) {
+    console.error('Error: ETSY_API_KEY environment variable is required');
+    process.exit(1);
+  }
+
+  const server = new EtsyMCPServer(config);
+  server.run().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+  });
+}