@iflow-mcp/dynamicendpoints-etsy-mcp 1.2.0

package/DEPLOYMENT_CHECKLIST.md

@@ -0,0 +1,206 @@
+# Smithery Deployment Checklist
+
+Use this checklist to verify your Etsy MCP server is ready for Smithery deployment.
+
+## ✅ Required Files
+
+- [x] `smithery.yaml` - Runtime configuration
+- [x] `package.json` - With `module` field pointing to `src/index.ts`
+- [x] `src/index.ts` - Exports default `createServer` function
+- [x] `tsconfig.json` - TypeScript configuration
+- [x] `.gitignore` - Excludes node_modules and build artifacts
+
+## ✅ Code Structure
+
+- [x] Default export: `createServer` function
+- [x] Configuration schema: `configSchema` exported with Zod
+- [x] Returns MCP Server object from `createServer`
+- [x] Stdio support: CLI entry point for local execution
+- [x] Config support: Accepts config from Smithery or environment
+
+## ✅ Dependencies
+
+- [x] `@modelcontextprotocol/sdk` in dependencies
+- [x] `axios` for HTTP requests
+- [x] `zod` for schema validation
+- [x] `@smithery/cli` in devDependencies
+- [x] TypeScript types installed
+
+## ✅ Scripts
+
+- [x] `npm run build` - Uses Smithery CLI
+- [x] `npm run dev` - Opens interactive playground
+- [x] `npm run compile` - TypeScript compilation (for testing)
+- [x] `npm start` - Runs compiled server
+
+## ✅ Testing
+
+### Local Testing
+```bash
+# Install dependencies
+npm install
+
+# Test compilation
+npm run compile
+
+# Test with Smithery playground
+npm run dev
+
+# Test direct execution
+ETSY_API_KEY=your_key npm start
+```
+
+### Verify These Work:
+- [ ] Server starts without errors
+- [ ] All 19 tools are listed
+- [ ] Configuration schema shows 3 fields
+- [ ] Tools execute and return responses
+
+## ✅ Configuration Schema
+
+The exported `configSchema` includes:
+- [x] `apiKey` (string, required) - With description
+- [x] `shopId` (string, optional) - With description
+- [x] `accessToken` (string, optional) - With description
+
+## ✅ Tools Exported
+
+### Read-Only (10 tools)
+- [x] search_listings
+- [x] get_listing
+- [x] get_shop
+- [x] get_shop_listings
+- [x] search_shops
+- [x] get_listing_inventory
+- [x] get_listing_images
+- [x] get_shop_sections
+- [x] get_trending_listings
+- [x] find_shops
+
+### Shop Management (9 tools)
+- [x] create_listing
+- [x] update_listing
+- [x] delete_listing
+- [x] update_listing_inventory
+- [x] upload_listing_image
+- [x] create_shop_section
+- [x] update_shop_section
+- [x] delete_shop_section
+- [x] update_shop
+
+## ✅ Documentation
+
+- [x] README.md - Main documentation
+- [x] SMITHERY_DEPLOYMENT.md - Deployment guide
+- [x] OAUTH_SETUP.md - OAuth setup instructions
+- [x] QUICK_REFERENCE.md - Quick reference guide
+- [x] .env.example - Environment template
+
+## ✅ GitHub Repository
+
+Before deploying:
+- [ ] Push all files to GitHub
+- [ ] Repository is public (or accessible to Smithery)
+- [ ] All commits are up to date
+- [ ] .gitignore excludes sensitive files
+
+## 🚀 Deployment Steps
+
+1. **Push to GitHub**
+   ```bash
+   git add .
+   git commit -m "Ready for Smithery deployment"
+   git push origin main
+   ```
+
+2. **Connect to Smithery**
+   - Go to https://smithery.ai/new
+   - Connect your GitHub account
+   - Select the `etsy_mcp` repository
+
+3. **Configure Server**
+   - Name: Etsy MCP Server
+   - Description: MCP server for Etsy API integration
+   - Category: E-commerce / API Integration
+
+4. **Deploy**
+   - Click "Deploy" button
+   - Wait for build to complete
+   - Test deployed server
+
+## ✅ Post-Deployment Verification
+
+After deployment, verify:
+- [ ] Server shows as "Running" in Smithery dashboard
+- [ ] All 19 tools are discoverable
+- [ ] Configuration form displays correctly
+- [ ] Test tools work with valid API key
+- [ ] Error messages are clear and helpful
+
+## 🧪 Testing Deployed Server
+
+### With Claude Desktop
+Add to `claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "etsy": {
+      "url": "https://server.smithery.ai/YOUR-USERNAME/etsy-mcp-server/mcp",
+      "config": {
+        "apiKey": "your_etsy_api_key"
+      }
+    }
+  }
+}
+```
+
+### With MCP Inspector
+```bash
+npx @modelcontextprotocol/inspector https://server.smithery.ai/YOUR-USERNAME/etsy-mcp-server/mcp
+```
+
+### Test These Operations:
+- [ ] Search for listings works
+- [ ] Get listing details works
+- [ ] Get shop information works
+- [ ] Error handling for invalid API key
+- [ ] Error handling for missing resources
+
+## 📊 Monitoring
+
+After deployment, check:
+- [ ] View usage metrics in Smithery dashboard
+- [ ] Monitor error logs for issues
+- [ ] Check performance data
+- [ ] Review user feedback
+
+## 🔧 Troubleshooting
+
+If deployment fails:
+
+1. **Check build logs** in Smithery dashboard
+2. **Verify locally** with `npm run build`
+3. **Test compilation** with `npm run compile`
+4. **Review errors** and fix TypeScript issues
+5. **Check dependencies** in package.json
+6. **Validate structure** matches Smithery requirements
+
+## ✅ Success Criteria
+
+Your deployment is successful when:
+- ✅ Build completes without errors
+- ✅ Server shows as "Running"
+- ✅ All tools are listed
+- ✅ Configuration form works
+- ✅ Test queries return results
+- ✅ Error messages are clear
+
+## 🎉 You're Ready!
+
+Once all items are checked, your Etsy MCP server is:
+- ✅ **Smithery-compatible**
+- ✅ **Production-ready**
+- ✅ **Fully documented**
+- ✅ **Ready to deploy**
+
+Click that Deploy button! 🚀

package/OAUTH_SETUP.md

@@ -0,0 +1,275 @@
+# Etsy OAuth Setup Guide
+
+This guide will help you set up OAuth 2.0 authentication to enable shop management features in the Etsy MCP server.
+
+## Why OAuth?
+
+While the Etsy API key allows you to **read** public data (search listings, view shops), you need an **OAuth access token** to:
+- Create new listings
+- Update or delete your listings
+- Manage shop sections
+- Update shop information
+- Manage inventory
+
+## Prerequisites
+
+1. An Etsy account with a shop
+2. An Etsy developer account ([sign up here](https://www.etsy.com/developers/register))
+3. A registered app in the Etsy Developer Portal
+
+## Step-by-Step OAuth Setup
+
+### Step 1: Create an Etsy App
+
+1. Go to [Etsy Developer Portal](https://www.etsy.com/developers/your-apps)
+2. Click **"Create a New App"**
+3. Fill in the required information:
+   - **App Name**: Your MCP Server name
+   - **Is this app for production?**: Choose based on your needs
+   - **Tell us about your app**: Brief description
+4. Click **"Read Terms and Create App"**
+
+### Step 2: Configure OAuth Settings
+
+1. In your app dashboard, go to **"API Keys & Access Tokens"**
+2. Note your **Keystring** (this is your `ETSY_API_KEY`)
+3. Under **OAuth Settings**, add a redirect URI:
+   - For local testing: `http://localhost:3000/callback`
+   - For production: Your production callback URL
+4. Save the settings
+
+### Step 3: Request Authorization
+
+Build an authorization URL with the following format:
+
+```
+https://www.etsy.com/oauth/connect?response_type=code&redirect_uri=YOUR_REDIRECT_URI&scope=listings_w%20shops_w%20shops_r%20listings_r&client_id=YOUR_KEYSTRING&state=YOUR_RANDOM_STATE&code_challenge=YOUR_CODE_CHALLENGE&code_challenge_method=S256
+```
+
+**Required Parameters:**
+- `response_type`: Always `code`
+- `redirect_uri`: Must match your registered URI (URL encoded)
+- `scope`: Space-separated permissions (URL encoded):
+  - `listings_r` - Read listings
+  - `listings_w` - Write/manage listings
+  - `shops_r` - Read shop info
+  - `shops_w` - Update shop info
+  - `transactions_r` - Read orders
+  - `transactions_w` - Update orders
+- `client_id`: Your app's Keystring
+- `state`: Random string for security
+- `code_challenge`: PKCE challenge (base64url encoded SHA256 hash)
+- `code_challenge_method`: Always `S256`
+
+### Step 4: Generate PKCE Code Verifier and Challenge
+
+PKCE (Proof Key for Code Exchange) is required for security. Here's a Node.js example:
+
+```javascript
+const crypto = require('crypto');
+
+// Generate code verifier
+const codeVerifier = crypto.randomBytes(32).toString('base64url');
+
+// Generate code challenge
+const codeChallenge = crypto
+  .createHash('sha256')
+  .update(codeVerifier)
+  .digest('base64url');
+
+console.log('Code Verifier:', codeVerifier);
+console.log('Code Challenge:', codeChallenge);
+```
+
+**Save the code verifier** - you'll need it in the next step!
+
+### Step 5: User Authorization
+
+1. Open the authorization URL in a browser
+2. Log in to Etsy (if not already logged in)
+3. Review the permissions your app is requesting
+4. Click **"Allow Access"**
+5. You'll be redirected to your callback URL with a `code` parameter:
+   ```
+   http://localhost:3000/callback?code=AUTHORIZATION_CODE&state=YOUR_STATE
+   ```
+
+### Step 6: Exchange Code for Access Token
+
+Make a POST request to exchange the authorization code for an access token:
+
+```bash
+curl -X POST "https://api.etsy.com/v3/public/oauth/token" \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -d "grant_type=authorization_code" \
+  -d "client_id=YOUR_KEYSTRING" \
+  -d "redirect_uri=YOUR_REDIRECT_URI" \
+  -d "code=AUTHORIZATION_CODE" \
+  -d "code_verifier=YOUR_CODE_VERIFIER"
+```
+
+**Node.js Example:**
+
+```javascript
+const axios = require('axios');
+
+const data = new URLSearchParams({
+  grant_type: 'authorization_code',
+  client_id: 'YOUR_KEYSTRING',
+  redirect_uri: 'http://localhost:3000/callback',
+  code: 'AUTHORIZATION_CODE_FROM_CALLBACK',
+  code_verifier: 'YOUR_CODE_VERIFIER_FROM_STEP_4'
+});
+
+axios.post('https://api.etsy.com/v3/public/oauth/token', data, {
+  headers: { 'Content-Type': 'application/x-www-form-urlencoded' }
+})
+.then(response => {
+  console.log('Access Token:', response.data.access_token);
+  console.log('Refresh Token:', response.data.refresh_token);
+  console.log('Expires In:', response.data.expires_in, 'seconds');
+})
+.catch(error => {
+  console.error('Error:', error.response?.data || error.message);
+});
+```
+
+**Response:**
+```json
+{
+  "access_token": "YOUR_ACCESS_TOKEN",
+  "token_type": "Bearer",
+  "expires_in": 3600,
+  "refresh_token": "YOUR_REFRESH_TOKEN"
+}
+```
+
+### Step 7: Add Token to Environment
+
+Add the access token to your `.env` file:
+
+```bash
+ETSY_API_KEY=your_keystring_here
+ETSY_SHOP_ID=your_shop_id
+ETSY_ACCESS_TOKEN=your_access_token_here
+```
+
+Or add it to your Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "etsy": {
+      "command": "node",
+      "args": ["C:\\path\\to\\etsy_mcp\\build\\index.js"],
+      "env": {
+        "ETSY_API_KEY": "your_keystring",
+        "ETSY_ACCESS_TOKEN": "your_access_token"
+      }
+    }
+  }
+}
+```
+
+## Token Refresh
+
+Access tokens expire after 1 hour. Use the refresh token to get a new access token:
+
+```bash
+curl -X POST "https://api.etsy.com/v3/public/oauth/token" \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -d "grant_type=refresh_token" \
+  -d "client_id=YOUR_KEYSTRING" \
+  -d "refresh_token=YOUR_REFRESH_TOKEN"
+```
+
+## Quick Test Script
+
+Save this as `oauth-helper.js`:
+
+```javascript
+const crypto = require('crypto');
+const readline = require('readline');
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout
+});
+
+const CLIENT_ID = 'YOUR_KEYSTRING_HERE';
+const REDIRECT_URI = 'http://localhost:3000/callback';
+const STATE = crypto.randomBytes(16).toString('hex');
+const CODE_VERIFIER = crypto.randomBytes(32).toString('base64url');
+const CODE_CHALLENGE = crypto.createHash('sha256').update(CODE_VERIFIER).digest('base64url');
+
+const scopes = 'listings_r listings_w shops_r shops_w';
+const authUrl = `https://www.etsy.com/oauth/connect?response_type=code&redirect_uri=${encodeURIComponent(REDIRECT_URI)}&scope=${encodeURIComponent(scopes)}&client_id=${CLIENT_ID}&state=${STATE}&code_challenge=${CODE_CHALLENGE}&code_challenge_method=S256`;
+
+console.log('\n=== Etsy OAuth Helper ===\n');
+console.log('1. Open this URL in your browser:\n');
+console.log(authUrl);
+console.log('\n2. After authorization, copy the "code" parameter from the redirect URL\n');
+
+rl.question('Enter the authorization code: ', async (code) => {
+  const axios = require('axios');
+  
+  try {
+    const data = new URLSearchParams({
+      grant_type: 'authorization_code',
+      client_id: CLIENT_ID,
+      redirect_uri: REDIRECT_URI,
+      code: code.trim(),
+      code_verifier: CODE_VERIFIER
+    });
+
+    const response = await axios.post('https://api.etsy.com/v3/public/oauth/token', data, {
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' }
+    });
+
+    console.log('\n✅ Success! Add these to your .env file:\n');
+    console.log(`ETSY_ACCESS_TOKEN=${response.data.access_token}`);
+    console.log(`ETSY_REFRESH_TOKEN=${response.data.refresh_token}`);
+    console.log(`\nToken expires in: ${response.data.expires_in} seconds`);
+  } catch (error) {
+    console.error('\n❌ Error:', error.response?.data || error.message);
+  }
+  
+  rl.close();
+});
+```
+
+Run it with:
+```bash
+npm install axios
+node oauth-helper.js
+```
+
+## Troubleshooting
+
+### "Invalid redirect_uri"
+Make sure the redirect URI in your request exactly matches the one registered in your app settings.
+
+### "Invalid code_verifier"
+Ensure you're using the same code_verifier that was used to generate the code_challenge.
+
+### "Token expired"
+Access tokens expire after 1 hour. Use the refresh token to get a new one.
+
+### "Insufficient scope"
+Request the appropriate scopes during authorization:
+- `listings_w` for creating/updating listings
+- `shops_w` for updating shop info
+
+## Security Best Practices
+
+1. **Never commit tokens** to version control - use `.env` files
+2. **Store refresh tokens securely** - they don't expire
+3. **Use PKCE** - always include code_challenge
+4. **Validate state parameter** - prevents CSRF attacks
+5. **Use HTTPS in production** - HTTP is only for local testing
+
+## Resources
+
+- [Etsy OAuth Documentation](https://developers.etsy.com/documentation/essentials/authentication/)
+- [Etsy API Reference](https://developers.etsy.com/documentation/reference)
+- [OAuth 2.0 PKCE Specification](https://tools.ietf.org/html/rfc7636)