ebay-mcp 1.4.5 → 1.4.6

package/LICENSE

@@ -1,201 +1,21 @@
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
-
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-   1. Definitions.
-
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
-
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
-
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
-
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
-
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
-
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
-
-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
-
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
-
-      "Contribution" shall mean any work of authorship, including
-      the original version of the Work and any modifications or additions
-      to that Work or Derivative Works thereof, that is intentionally
-      submitted to Licensor for inclusion in the Work by the copyright owner
-      or by an individual or Legal Entity authorized to submit on behalf of
-      the copyright owner. For the purposes of this definition, "submitted"
-      means any form of electronic, verbal, or written communication sent
-      to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control systems,
-      and issue tracking systems that are managed by, or on behalf of, the
-      Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
-      subsequently incorporated within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
-
-      You may add Your own copyright statement to Your modifications and
-      may provide additional or different license terms and conditions
-      for use, reproduction, or distribution of Your modifications, or
-      for any such Derivative Works as a whole, provided Your use,
-      reproduction, and distribution of the Work otherwise complies with
-      the conditions stated in this License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for reasonable and customary use in describing the
-      origin of the Work and reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or redistributing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or consequential damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or any and all
-      other commercial damages or losses), even if such Contributor
-      has been advised of the possibility of such damages.
-
-   9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may act only
-      on Your own behalf and on Your sole responsibility, not on behalf
-      of any other Contributor, and only if You agree to indemnify,
-      defend, and hold each Contributor harmless for any liability
-      incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or additional liability.
-
-   END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright [2025] [Yosef hayim Sabag]
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
+MIT License
+
+Copyright (c) 2025 Yosef Hayim Sabag
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,5 +1,4 @@
 # eBay API MCP Server
-
 <div align="center">
 
 [![npm version](https://img.shields.io/npm/v/ebay-mcp)](https://www.npmjs.com/package/ebay-mcp)
@@ -7,6 +6,9 @@
 [![Tests](https://img.shields.io/badge/tests-890%2B%20passing-brightgreen)](tests/)
 [![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
+[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/yosefhayim-ebay-api-mcp-server-badge.png)](https://mseep.ai/app/yosefhayim-ebay-api-mcp-server)
+<a href="https://www.buymeacoffee.com/yosefhayim" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>
+
 A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server providing AI assistants with comprehensive access to eBay's Sell APIs. Includes 230+ tools for inventory management, order fulfillment, marketing campaigns, analytics, and more.
 
 **API Coverage:** 99.1% (~110 of 111 eBay Sell API endpoints)
@@ -30,9 +32,10 @@ This is an **open-source project** provided "as is" without warranty of any kind
   - Any other direct or indirect damages
 
 - **eBay API Usage:** This project is an unofficial third-party implementation and is **NOT affiliated with, endorsed by, or sponsored by eBay Inc.** You are solely responsible for:
-  - Complying with [eBay's API Terms of Use](https://developer.ebay.com/join/api_license_agreement)
+  - Complying with [eBay's API Terms of Use](https://developer.ebay.com/join/api-license-agreement)
   - Ensuring your usage stays within eBay's rate limits and policies
   - Managing your eBay Developer credentials securely
+  - Understanding and complying with [eBay's data handling requirements](https://developer.ebay.com/api-docs/static/data-handling-update.html)
   - Any actions performed through the API
 
 - **Use at Your Own Risk:** This software is provided for educational and development purposes. Users must:
@@ -126,6 +129,7 @@ Add this server to your MCP client configuration:
 **Claude Desktop:**
 
 Edit your Claude Desktop config file:
+
 - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
 - Windows: `%APPDATA%/Claude/claude_desktop_config.json`
 - Linux: `~/.config/Claude/claude_desktop_config.json`
@@ -175,6 +179,8 @@ Restart your MCP client (Claude Desktop, etc.) and start using eBay tools throug
 
 ## Configuration
 
+> 📖 **For a comprehensive configuration guide with detailed explanations of all environment variables, OAuth flow steps, and troubleshooting, see [Configuration Documentation](docs/auth/CONFIGURATION.md).**
+
 ### Environment Variables
 
 Create a `.env` file with your eBay credentials:
@@ -192,28 +198,32 @@ EBAY_USER_REFRESH_TOKEN=your_refresh_token
 ### OAuth Authentication
 
 **Client Credentials (Automatic):**
+
 - Default authentication method
 - 1,000 requests/day
 - No setup required beyond client ID and secret
 
 **User Tokens (Recommended for Production):**
+
 - 10,000-50,000 requests/day
 - Use `ebay_get_oauth_url` tool to generate authorization URL
 - Add `EBAY_USER_REFRESH_TOKEN` to `.env` after OAuth flow
 - Tokens refresh automatically
 
-For detailed OAuth setup, see the [OAuth documentation](docs/auth/).
+For detailed OAuth setup and comprehensive configuration guide, see the [Configuration Documentation](docs/auth/CONFIGURATION.md).
 
 ### MCP Client Compatibility
 
 This server is compatible with any MCP client that supports STDIO transport:
 
 **Tested and Supported:**
+
 - ✅ **Claude Desktop** (macOS, Windows, Linux) - Full support
 - ✅ **MCP Inspector** - For development and testing
 - ✅ **Custom MCP Clients** - Via STDIO or HTTP transport
 
 **Configuration Requirements:**
+
 - MCP Protocol version: 1.0+
 - Transport: STDIO (default) or HTTP
 - Node.js runtime: 18.0.0 or higher
@@ -221,6 +231,7 @@ This server is compatible with any MCP client that supports STDIO transport:
 **Other MCP Clients:**
 
 While not specifically tested, the server should work with any MCP-compliant client including:
+
 - Continue.dev
 - Other editors with MCP support
 - Custom implementations
@@ -232,21 +243,25 @@ If you successfully use this server with another MCP client, please let us know
 Understanding eBay API rate limits is crucial for production use:
 
 **Client Credentials (Default):**
+
 - **Daily Limit:** 1,000 requests per day
 - **Best For:** Development, testing, low-volume operations
 - **Setup:** Automatic with just Client ID and Secret
 
 **User Token (Recommended):**
+
 - **Daily Limit:** 10,000-50,000 requests per day (varies by account type)
 - **Best For:** Production, high-volume operations
 - **Setup:** Requires OAuth flow (use `ebay_get_oauth_url` tool)
 
 **Rate Limit Tiers by Account Type:**
+
 - Individual Developer: 10,000 requests/day
 - Commercial Developer: 25,000 requests/day
 - Enterprise: 50,000+ requests/day (custom limits)
 
 **Rate Limit Best Practices:**
+
 1. Use user tokens for production workloads
 2. Implement exponential backoff on rate limit errors
 3. Cache responses when possible
@@ -257,6 +272,7 @@ Understanding eBay API rate limits is crucial for production use:
 **Handling Rate Limits:**
 
 When you hit a rate limit, the API returns a 429 status code. The server will:
+
 - Automatically retry with exponential backoff
 - Inform you of rate limit errors
 - Suggest upgrading to user token authentication
@@ -279,6 +295,7 @@ The server provides 230+ tools organized into the following categories:
 - **Token Management** - OAuth URL generation, token management
 
 **Example Tools:**
+
 - `ebay_get_inventory_items` - List all inventory items
 - `ebay_get_orders` - Retrieve seller orders
 - `ebay_create_offer` - Create new listing offer
@@ -402,6 +419,7 @@ docker-compose up -d
 Environment variables should be configured in `.env` file before running Docker commands. The container will automatically use your `.env` configuration.
 
 **Use Cases for Docker:**
+
 - Production deployments
 - Consistent development environments
 - CI/CD pipelines
@@ -420,6 +438,7 @@ npm run start:http
 ```
 
 **HTTP Mode Features:**
+
 - RESTful API endpoints for all tools
 - Interactive API documentation
 - Useful for testing tools without an MCP client
@@ -427,6 +446,7 @@ npm run start:http
 - Helmet security headers
 
 **When to Use HTTP Mode:**
+
 - Testing individual tools during development
 - Building custom integrations
 - Debugging API responses
@@ -464,6 +484,7 @@ Contributions are welcome! Here's how to get started:
 6. Push to your fork and open a Pull Request
 
 **Before submitting:**
+
 - Ensure all tests pass
 - Follow TypeScript best practices
 - Update documentation as needed
@@ -480,6 +501,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
 **Problem:** The eBay MCP server doesn't show up in your MCP client.
 
 **Solutions:**
+
 1. Verify the config file path is correct for your OS
 2. Check JSON syntax is valid (use a JSON validator)
 3. Ensure environment variables are properly set
@@ -491,6 +513,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
 **Problem:** "Invalid credentials" or "Authentication failed" errors.
 
 **Solutions:**
+
 1. Verify your `EBAY_CLIENT_ID` and `EBAY_CLIENT_SECRET` are correct
 2. Ensure you're using the right environment (sandbox vs production)
 3. Check if your app keys are active in the eBay Developer Portal
@@ -502,6 +525,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
 **Problem:** "Rate limit exceeded" errors.
 
 **Solutions:**
+
 1. Upgrade to user token authentication (10k-50k requests/day)
 2. Implement request throttling in your usage
 3. Check your current rate limit in the Developer Portal
@@ -512,6 +536,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
 **Problem:** Tools return unexpected errors or empty results.
 
 **Solutions:**
+
 1. Verify you're using the correct environment (sandbox vs production)
 2. Ensure you have proper permissions/scopes for the operation
 3. Check eBay API status: https://developer.ebay.com/support/api-status
@@ -531,6 +556,7 @@ npm run diagnose:export
 ```
 
 The diagnostic tool checks:
+
 - Environment variable configuration
 - eBay API connectivity
 - Authentication status
@@ -554,7 +580,11 @@ If you're still experiencing issues:
 ### Documentation
 
 - [eBay Developer Portal](https://developer.ebay.com/) - API documentation and credentials
+- [eBay API License Agreement](https://developer.ebay.com/join/api-license-agreement) - Terms of use and compliance requirements
+- [eBay Data Handling Requirements](https://developer.ebay.com/api-docs/static/data-handling-update.html) - Important data protection and privacy guidelines
+- [eBay API Status](https://developer.ebay.com/support/api-status) - Real-time API health and status
 - [MCP Documentation](https://modelcontextprotocol.io/) - Model Context Protocol specification
+- [OAuth Quick Reference](docs/auth/OAUTH_QUICK_REFERENCE.md) - **Complete OAuth authentication guide with scopes, troubleshooting, and examples**
 - [OAuth Setup Guide](docs/auth/) - Detailed authentication configuration
 - [Contributing Guidelines](CONTRIBUTING.md) - How to contribute to this project
 - [Code of Conduct](CODE_OF_CONDUCT.md) - Community guidelines and expectations

package/build/auth/oauth.js

@@ -25,11 +25,11 @@ function updateEnvFile(updates) {
             }
         }
         writeFileSync(envPath, envContent, 'utf-8');
-        console.log('✅ Updated .env file with new tokens');
+        // Tokens updated silently - console output interferes with MCP JSON protocol
     }
     catch (error) {
-        console.error('⚠️  Failed to update .env file:', error instanceof Error ? error.message : error);
-        console.error('   Please manually update your .env file with the new tokens');
+        // Silent failure - error logging interferes with MCP JSON protocol
+        // If needed, check .env file manually
     }
 }
 /**
@@ -245,10 +245,8 @@ export class EbayOAuthClient {
                 userRefreshTokenExpiry: now + tokenData.refresh_token_expires_in * 1000,
                 scope: tokenData.scope,
             };
-            // Inform user to save refresh token to .env
-            console.log('\nToken exchange successful!');
-            console.log('To persist your authentication, add this to your .env file:');
-            console.log(`EBAY_USER_REFRESH_TOKEN="${tokenData.refresh_token}"\n`);
+            // Tokens are automatically saved to .env file by updateEnvFile()
+            // No console output needed here to avoid interfering with MCP JSON protocol
             return tokenData;
         }
         catch (error) {
@@ -307,7 +305,7 @@ export class EbayOAuthClient {
             // If eBay provided a new refresh token, update it too
             if (tokenData.refresh_token && tokenData.refresh_token !== process.env.EBAY_USER_REFRESH_TOKEN) {
                 envUpdates.EBAY_USER_REFRESH_TOKEN = tokenData.refresh_token;
-                console.log('\n🔄 eBay issued a new refresh token - updating .env file');
+                // New refresh token updated silently
             }
             // Write updates to .env file
             updateEnvFile(envUpdates);

package/build/tools/definitions/token-management.js

@@ -12,7 +12,27 @@ import { z } from 'zod';
 export const tokenManagementTools = [
     {
         name: 'ebay_get_oauth_url',
-        description: 'Generate the eBay OAuth authorization URL for user consent. The user should open this URL in a browser to grant permissions to the application. This supports the OAuth 2.0 Authorization Code grant flow. The redirect URI can be provided as a parameter or will be read from EBAY_REDIRECT_URI environment variable.\n\nIMPORTANT: eBay has different OAuth scopes available for production vs sandbox environments:\n- Sandbox includes additional Buy API scopes (e.g., buy.order.readonly, buy.guest.order, buy.shopping.cart) and extended Identity scopes\n- Production includes sell.edelivery, commerce.message (explicit), and commerce.shipping scopes not available in sandbox\n- If you provide custom scopes, they will be validated against the current environment (set via EBAY_ENVIRONMENT). Any scopes not valid for the environment will generate warnings.',
+        description: 'Generate the eBay OAuth authorization URL for user consent. The user should open this URL in a browser to grant permissions to the application. This supports the OAuth 2.0 Authorization Code grant flow. The redirect URI can be provided as a parameter or will be read from EBAY_REDIRECT_URI environment variable.\n\n' +
+            'IMPORTANT: eBay has different OAuth scopes available for production vs sandbox environments:\n' +
+            '- Sandbox includes additional Buy API scopes (e.g., buy.order.readonly, buy.guest.order, buy.shopping.cart) and extended Identity scopes\n' +
+            '- Production includes sell.edelivery, commerce.message (explicit), and commerce.shipping scopes not available in sandbox\n' +
+            '- If you provide custom scopes, they will be validated against the current environment (set via EBAY_ENVIRONMENT). Any scopes not valid for the environment will generate warnings.\n\n' +
+            'OAUTH FLOW INSTRUCTIONS:\n' +
+            '1. Generate OAuth URL with this tool (optionally specify scopes)\n' +
+            '2. User opens URL in browser, authorizes, and gets redirected with a code parameter\n' +
+            '3. Use ebay_exchange_authorization_code tool with the code (URL-encoded format accepted)\n' +
+            '4. Tokens are automatically stored and will auto-refresh every 2 hours\n\n' +
+            'COMMON SCOPES:\n' +
+            '- Basic (always included): https://api.ebay.com/oauth/api_scope\n' +
+            '- Inventory: https://api.ebay.com/oauth/api_scope/sell.inventory\n' +
+            '- Inventory (readonly): https://api.ebay.com/oauth/api_scope/sell.inventory.readonly\n' +
+            '- Account: https://api.ebay.com/oauth/api_scope/sell.account\n' +
+            '- Fulfillment: https://api.ebay.com/oauth/api_scope/sell.fulfillment\n\n' +
+            'TROUBLESHOOTING:\n' +
+            '- Authorization codes expire in ~5 minutes - get fresh code if "invalid grant" error\n' +
+            '- "Insufficient permissions" errors mean you need to re-authorize with additional scopes\n' +
+            '- OAuth URL format: Use + to separate scopes (e.g., scope=scope1+scope2), not %2B\n' +
+            '- Refresh tokens last 18 months and are saved to .env file for persistence',
         inputSchema: {
             redirectUri: z
                 .string()
@@ -100,4 +120,29 @@ export const tokenManagementTools = [
             description: 'Success response',
         },
     },
+    {
+        name: 'ebay_exchange_authorization_code',
+        description: 'Exchange an OAuth authorization code for access and refresh tokens. This completes the OAuth 2.0 Authorization Code grant flow. After the user authorizes the application using the URL from ebay_get_oauth_url, eBay redirects back with an authorization code in the URL. Use this tool to exchange that code for tokens that can be used to make API calls. The tokens will be automatically stored and used for subsequent API requests.\n\n' +
+            'IMPORTANT NOTES:\n' +
+            '- Authorization codes expire in ~5 minutes - if you get "invalid grant" error, get a fresh code\n' +
+            '- Codes can be URL-encoded (e.g., v%5E1.1%23...) - this tool automatically decodes them\n' +
+            '- Extract the code parameter from the redirect URL: https://auth2.ebay.com/...&code=YOUR_CODE&expires_in=299\n' +
+            '- Tokens are saved to .env file and will auto-refresh every 2 hours\n' +
+            '- Refresh tokens last 18 months before requiring re-authorization\n\n' +
+            'COMMON ERRORS:\n' +
+            '- "invalid or was issued to another client": Code expired, get fresh code\n' +
+            '- "Insufficient permissions": Re-run OAuth flow with additional scopes in ebay_get_oauth_url\n\n' +
+            'For complete OAuth guide with scopes, troubleshooting, and examples, see: docs/auth/OAUTH_QUICK_REFERENCE.md',
+        inputSchema: {
+            code: z
+                .string()
+                .min(1)
+                .describe('The authorization code received from eBay after user authorization. This is the "code" parameter in the redirect URL.'),
+        },
+        outputSchema: {
+            type: 'object',
+            properties: {},
+            description: 'Token exchange response including access token, refresh token, and expiry times',
+        },
+    },
 ];

package/build/tools/index.js

@@ -309,6 +309,36 @@ export async function executeTool(api, toolName, args) {
                 scopes: internalTokens?.scope ? internalTokens.scope.split(' ') : [],
             };
         }
+        case 'ebay_exchange_authorization_code': {
+            const code = args.code;
+            if (!code) {
+                throw new Error('Authorization code is required');
+            }
+            try {
+                // URL-decode the code if it's URL-encoded (contains % characters)
+                const decodedCode = code.includes('%') ? decodeURIComponent(code) : code;
+                // Get the OAuth client
+                const authClient = api.getAuthClient().getOAuthClient();
+                // Exchange the authorization code for tokens
+                const tokenData = await authClient.exchangeCodeForToken(decodedCode);
+                return {
+                    success: true,
+                    message: 'Authorization code successfully exchanged for tokens. Tokens have been stored and will be used for subsequent API requests.',
+                    tokenData: {
+                        accessToken: `${tokenData.access_token.substring(0, 20)}...${tokenData.access_token.slice(-10)}`,
+                        refreshToken: `${tokenData.refresh_token.substring(0, 20)}...${tokenData.refresh_token.slice(-10)}`,
+                        expiresIn: tokenData.expires_in,
+                        refreshTokenExpiresIn: tokenData.refresh_token_expires_in,
+                        tokenType: tokenData.token_type,
+                        scope: tokenData.scope,
+                    },
+                    note: 'The refresh token has been saved to your .env file for future use.',
+                };
+            }
+            catch (error) {
+                throw new Error(`Failed to exchange authorization code: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
         case 'ebay_refresh_access_token': {
             const authClient = api.getAuthClient().getOAuthClient();
             // Check if user tokens are available

package/package.json

@@ -1,117 +1,117 @@
 {
-	"name": "ebay-mcp",
-	"version": "1.4.5",
-	"description": "MCP server for eBay APIs - provides access to eBay developer functionality through MCP (Model Context Protocol)",
-	"type": "module",
-	"main": "build/index.js",
-	"types": "build/index.d.ts",
-	"bin": {
-		"ebay-mcp": "build/index.js"
-	},
-	"scripts": {
-		"build": "tsc && tsc-alias",
-		"watch": "tsc --watch",
-		"dev": "tsx src/index.ts",
-		"dev:http": "tsx src/server-http.ts",
-		"start": "node build/index.js",
-		"start:http": "node build/server-http.js",
-		"clean": "rm -rf build",
-		"prepare": "npm run build",
-		"postinstall": "npm run auto-setup --if-present || true",
-		"setup": "tsx src/scripts/interactive-setup.ts",
-		"auto-setup": "node build/scripts/auto-setup.js",
-		"diagnose": "tsx src/scripts/diagnostics.ts",
-		"diagnose:export": "tsx src/scripts/diagnostics.ts --export",
-		"typecheck": "tsc --noEmit",
-		"test": "vitest run",
-		"test:watch": "vitest",
-		"test:ui": "vitest --ui",
-		"test:coverage": "vitest run --coverage",
-		"test:integration": "vitest run tests/integration",
-		"download:specs": "tsx src/scripts/download-specs.ts",
-		"test:endpoints": "tsx src/scripts/test-endpoints.ts",
-		"generate:types": "bash src/scripts/generate-types.sh",
-		"lint": "eslint .",
-		"lint:fix": "eslint . --fix",
-		"format": "prettier --write \"src/**/*.{ts,js,json,md}\" \"tests/**/*.{ts,js,json}\"",
-		"format:check": "prettier --check \"src/**/*.{ts,js,json,md}\" \"tests/**/*.{ts,js,json}\"",
-		"check": "npm run typecheck && npm run lint && npm run format:check",
-		"docker:build": "docker-compose build",
-		"docker:up": "docker-compose up -d",
-		"docker:down": "docker-compose down",
-		"docker:logs": "docker-compose logs -f",
-		"docker:restart": "docker-compose restart"
-	},
-	"keywords": [
-		"mcp",
-		"ebay",
-		"ebay-api",
-		"model-context-protocol",
-		"ai-tools",
-		"ai",
-		"llm",
-		"mcp",
-		"documentation",
-		"api",
-		"ebay",
-		"server",
-		"backend"
-	],
-	"author": "Yosef Hayim Sabag",
-	"license": "MIT",
-	"files": [
-		"build/**/*.js",
-		"build/index.d.ts",
-		"build/server-http.d.ts",
-		"README.md"
-	],
-	"repository": {
-		"type": "git",
-		"url": "https://github.com/YosefHayim/ebay-mcp.git"
-	},
-	"homepage": "https://github.com/YosefHayim/ebay-mcp#readme",
-	"bugs": {
-		"url": "https://github.com/YosefHayim/ebay-mcp/issues"
-	},
-	"dependencies": {
-		"@modelcontextprotocol/sdk": "^1.21.1",
-		"axios": "^1.7.9",
-		"chalk": "^5.6.2",
-		"cors": "^2.8.5",
-		"dotenv": "^16.4.7",
-		"express": "^5.1.0",
-		"helmet": "^8.1.0",
-		"jose": "^6.1.1",
-		"jsonwebtoken": "^9.0.2",
-		"prompts": "^2.4.2",
-		"zod": "3",
-		"zod-to-json-schema": "^3.24.6"
-	},
-	"devDependencies": {
-		"@eslint/js": "^9.39.1",
-		"@types/cors": "^2.8.19",
-		"@types/express": "^5.0.5",
-		"@types/jsonwebtoken": "^9.0.10",
-		"@types/node": "^22.10.2",
-		"@types/prompts": "^2.4.9",
-		"@types/supertest": "^6.0.3",
-		"@vitest/coverage-v8": "^4.0.8",
-		"@vitest/ui": "^4.0.8",
-		"eslint": "^9.39.1",
-		"eslint-config-prettier": "^10.1.8",
-		"eslint-plugin-n": "^17.23.1",
-		"eslint-plugin-vitest": "^0.5.4",
-		"nock": "^14.0.10",
-		"openapi-typescript": "^7.10.1",
-		"prettier": "^3.6.2",
-		"supertest": "^7.1.4",
-		"tsc-alias": "^1.8.16",
-		"tsx": "^4.19.2",
-		"typescript": "^5.9.3",
-		"typescript-eslint": "^8.46.4",
-		"vitest": "^4.0.8"
-	},
-	"engines": {
-		"node": ">=18.0.0"
-	}
+  "name": "ebay-mcp",
+  "version": "1.4.6",
+  "description": "MCP server for eBay APIs - provides access to eBay developer functionality through MCP (Model Context Protocol)",
+  "type": "module",
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "bin": {
+    "ebay-mcp": "build/index.js"
+  },
+  "scripts": {
+    "build": "tsc && tsc-alias",
+    "watch": "tsc --watch",
+    "dev": "tsx src/index.ts",
+    "dev:http": "tsx src/server-http.ts",
+    "start": "node build/index.js",
+    "start:http": "node build/server-http.js",
+    "clean": "rm -rf build",
+    "prepare": "npm run build",
+    "postinstall": "npm run auto-setup --if-present || true",
+    "setup": "tsx src/scripts/interactive-setup.ts",
+    "auto-setup": "node build/scripts/auto-setup.js",
+    "diagnose": "tsx src/scripts/diagnostics.ts",
+    "diagnose:export": "tsx src/scripts/diagnostics.ts --export",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
+    "test:integration": "vitest run tests/integration",
+    "download:specs": "tsx src/scripts/download-specs.ts",
+    "test:endpoints": "tsx src/scripts/test-endpoints.ts",
+    "generate:types": "bash src/scripts/generate-types.sh",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write \"src/**/*.{ts,js,json,md}\" \"tests/**/*.{ts,js,json}\"",
+    "format:check": "prettier --check \"src/**/*.{ts,js,json,md}\" \"tests/**/*.{ts,js,json}\"",
+    "check": "npm run typecheck && npm run lint && npm run format:check",
+    "docker:build": "docker-compose build",
+    "docker:up": "docker-compose up -d",
+    "docker:down": "docker-compose down",
+    "docker:logs": "docker-compose logs -f",
+    "docker:restart": "docker-compose restart"
+  },
+  "keywords": [
+    "mcp",
+    "ebay",
+    "ebay-api",
+    "model-context-protocol",
+    "ai-tools",
+    "ai",
+    "llm",
+    "mcp",
+    "documentation",
+    "api",
+    "ebay",
+    "server",
+    "backend"
+  ],
+  "author": "Yosef Hayim Sabag",
+  "license": "MIT",
+  "files": [
+    "build/**/*.js",
+    "build/index.d.ts",
+    "build/server-http.d.ts",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/YosefHayim/ebay-mcp.git"
+  },
+  "homepage": "https://github.com/YosefHayim/ebay-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/YosefHayim/ebay-mcp/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.21.1",
+    "axios": "^1.7.9",
+    "chalk": "^5.6.2",
+    "cors": "^2.8.5",
+    "dotenv": "^17.2.3",
+    "express": "^5.1.0",
+    "helmet": "^8.1.0",
+    "jose": "^6.1.2",
+    "jsonwebtoken": "^9.0.2",
+    "prompts": "^2.4.2",
+    "zod": "3",
+    "zod-to-json-schema": "^3.25.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.5",
+    "@types/jsonwebtoken": "^9.0.10",
+    "@types/node": "^24.10.1",
+    "@types/prompts": "^2.4.9",
+    "@types/supertest": "^6.0.3",
+    "@vitest/coverage-v8": "^4.0.13",
+    "@vitest/ui": "^4.0.8",
+    "eslint": "^9.39.1",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-n": "^17.23.1",
+    "eslint-plugin-vitest": "^0.5.4",
+    "nock": "^14.0.10",
+    "openapi-typescript": "^7.10.1",
+    "prettier": "^3.6.2",
+    "supertest": "^7.1.4",
+    "tsc-alias": "^1.8.16",
+    "tsx": "^4.19.2",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.47.0",
+    "vitest": "^4.0.8"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
 }