Contributing

Complete guide to contributing to the eBay MCP Server project - from setup to pull requests

Contributing

Thank you for considering contributing to the eBay MCP Server! This guide will help you get started with development, understand our processes, and make meaningful contributions.

Ways to Contribute

There are many ways to contribute to the project:

Bug Fixes

Find and fix bugs in the codebase

New Features

Implement new eBay API tools or MCP capabilities

Documentation

Improve guides, examples, or API references

Tests

Add or improve test coverage

Code Quality

Refactor code or improve performance

Ideas

Suggest new features or improvements

Getting Started

Prerequisites

Before you begin, ensure you have:

• Node.js >= 18.0.0
• npm or pnpm (both supported)
• Git installed and configured
• eBay Developer Account (for testing)
• Basic understanding of TypeScript and Node.js

Development Setup

1. Fork the Repository

   Fork the ebay-mcp-server repository to your GitHub account.

2. Clone Your Fork

   git clone https://github.com/YOUR_USERNAME/ebay-mcp-server.git
   cd ebay-mcp-server
   
3. Install Dependencies

   npm install
   # or
   pnpm install
   
4. Configure Environment

   # Copy environment template
   cp .env.example .env
   
   # Edit .env with your eBay credentials
   EBAY_CLIENT_ID=your_client_id
   EBAY_CLIENT_SECRET=your_client_secret
   EBAY_ENVIRONMENT=sandbox
   EBAY_REDIRECT_URI=your_runame
   

   See OAuth Setup for detailed instructions.

5. Build the Project

   npm run build
   
6. Run Tests

   npm test
   

   Ensure all tests pass before making changes.

Development Workflow

# Start development server (STDIO mode)
npm run dev

# Start development server (HTTP mode)
npm run dev:http

# Watch mode for TypeScript compilation
npm run watch

# Run tests in watch mode
npm run test:watch

# Run tests with UI dashboard
npm run test:ui

# Check code quality (typecheck + lint + format)
npm run check

# Format code
npm run format

# Generate types from OpenAPI specs
npm run generate:types

Project Structure

Understanding the project structure helps you navigate and contribute effectively:

ebay-mcp-server/
├── src/
│   ├── api/              # eBay API implementations
│   │   ├── client.ts     # HTTP client with interceptors
│   │   ├── index.ts      # API facade
│   │   └── [domain]/     # API categories
│   ├── auth/             # OAuth & token management
│   ├── tools/            # MCP tool definitions
│   ├── types/            # TypeScript types & enums
│   ├── utils/            # Zod validation schemas
│   └── config/           # Environment configuration
├── tests/
│   ├── unit/             # Unit tests
│   ├── integration/      # Integration tests
│   └── helpers/          # Test utilities
├── docs/                 # OpenAPI specifications
└── scripts/              # Build and setup scripts

See Architecture for detailed information.

Making Changes

Creating a Feature Branch

# Create and checkout a new branch
git checkout -b feature/amazing-feature

# Or for bug fixes
git checkout -b fix/bug-description

Branch Naming Conventions

Type	Format	Example
Feature	feature/description	feature/add-bulk-update
Bug Fix	fix/description	fix/token-refresh-error
Documentation	docs/description	docs/improve-oauth-guide
Refactoring	refactor/description	refactor/simplify-client
Tests	test/description	test/add-inventory-tests

Development Guidelines

1. Code Style

TypeScript Best Practices:

// ✅ Good: Use types over interfaces
type UserToken = {
  accessToken: string;
  refreshToken: string;
  expiresAt: number;
};

// ✅ Good: Use native enums
import { MarketplaceId } from '@/types/ebay-enums.js';

// ✅ Good: Include JSDoc comments for complex functions
/**
 * Refresh the user access token using the refresh token
 * @returns Promise that resolves when token is refreshed
 * @throws Error if refresh token is expired or invalid
 */
async refreshUserToken(): Promise<void> {
  // Implementation
}

// ✅ Good: Use path aliases
import { EbayOAuthClient } from '@/auth/oauth.js';

// ✅ Good: Include file extensions in imports
import { validateSKU } from '@/utils/validation.js';

Code Quality:

Use TypeScript strict mode - All code must compile with strict checks

Validate inputs with Zod schemas - All external inputs must be validated

Follow existing patterns - Maintain consistency with the codebase

Keep functions small and focused - Each function should do one thing well

2. Writing Tests

All new code must include tests. See Testing Guide for details.

Test Requirements:

• Maintain 90%+ coverage on critical paths
• Test both success and error cases
• Use descriptive test names
• Follow AAA pattern (Arrange-Act-Assert)

Example Test:

import { describe, it, expect, beforeEach } from 'vitest';
import { EbayInventoryApi } from '@/api/listing-management/inventory.js';

describe('EbayInventoryApi', () => {
  let inventoryApi: EbayInventoryApi;

  beforeEach(() => {
    const mockClient = createMockClient();
    inventoryApi = new EbayInventoryApi(mockClient);
  });

  describe('getInventoryItem', () => {
    it('should fetch inventory item by SKU', async () => {
      // Arrange
      const sku = 'TEST-SKU-123';
      const mockItem = { sku, condition: 'NEW' };
      mockClient.get.mockResolvedValue(mockItem);

      // Act
      const result = await inventoryApi.getInventoryItem(sku);

      // Assert
      expect(result).toEqual(mockItem);
      expect(mockClient.get).toHaveBeenCalledWith(
        `/sell/inventory/v1/inventory_item/${sku}`
      );
    });

    it('should throw error for invalid SKU', async () => {
      // Arrange & Act & Assert
      await expect(
        inventoryApi.getInventoryItem('')
      ).rejects.toThrow('SKU is required');
    });
  });
});

3. Documentation

Update documentation when making changes:

Update README.md for major features

Update CHANGELOG.md with your changes

Add JSDoc comments for public APIs

Update this documentation site if needed

4. Commit Messages

We follow Conventional Commits specification:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types:

• feat: - A new feature
• fix: - A bug fix
• docs: - Documentation only changes
• style: - Code style changes (formatting, etc.)
• refactor: - Code change that neither fixes a bug nor adds a feature
• perf: - Performance improvements
• test: - Adding or updating tests
• chore: - Maintenance tasks

Examples:

feat(inventory): add bulk update inventory items tool

fix(auth): handle token refresh race condition

docs(readme): update OAuth setup instructions

test(marketing): add campaign status validation tests

chore(deps): update @modelcontextprotocol/sdk to 1.21.1

Good Commit Message:

feat(inventory): add support for inventory item groups

Implement getInventoryItemGroup and related operations:
- Add getInventoryItemGroup method
- Add createOrReplaceInventoryItemGroup method
- Add deleteInventoryItemGroup method
- Add Zod validation schemas
- Add unit and integration tests

Closes #123

Submitting Changes

Pull Request Process

1. Ensure Quality

   Before submitting, ensure:

   # All tests pass
   npm test
   
   # Code is formatted
   npm run format
   
   # Linting passes
   npm run lint
   
   # Type checking passes
   npm run typecheck
   
   # Or run all checks
   npm run check
   
2. Update Changelog

   Add your changes to CHANGELOG.md:

   ## [Unreleased]
   
   ### Added
   - Add bulk update inventory items tool (#123)
   
   ### Fixed
   - Fix token refresh race condition (#124)
   
3. Push to Your Fork

   git add .
   git commit -m "feat: add amazing feature"
   git push origin feature/amazing-feature
   
4. Create Pull Request

   1. Go to the repository
   2. Click “New Pull Request”
   3. Select your fork and branch
   4. Fill out the PR template
   5. Submit for review

Pull Request Template

When creating a PR, include:

## Description
Brief description of what this PR does

## Type of Change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## How Has This Been Tested?
Describe the tests you ran to verify your changes

## Checklist
- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my own code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes
- [ ] Any dependent changes have been merged and published
- [ ] I have updated CHANGELOG.md

## Related Issues
Closes #(issue number)

Review Process

1. Automated Checks - CI runs tests and linting
2. Code Review - Maintainers review your code
3. Feedback - Address any requested changes
4. Approval - PR is approved by maintainer
5. Merge - PR is merged into main branch

Contribution Guidelines

Do’s

Follow the code style - Use the existing patterns and conventions

Write tests - Maintain or improve test coverage

Document changes - Update docs and comments

Keep PRs focused - One feature or fix per PR

Be respectful - Follow the code of conduct

Don’ts

Don’t skip tests - All code must be tested

Don’t break existing functionality - Ensure backward compatibility

Don’t ignore CI failures - Fix all test and lint failures

Don’t commit credentials - Never commit secrets or tokens

Adding New eBay APIs

To add support for a new eBay API:

1. Create API Implementation

   Create a new file in the appropriate category:

   // src/api/listing-management/product-compatibility.ts
   import type { EbayApiClient } from '@/api/client.js';
   
   export class EbayProductCompatibilityApi {
     constructor(private client: EbayApiClient) {}
   
     async getCompatibilityProperties(categoryTreeId: string) {
       return this.client.get(
         `/commerce/taxonomy/v1/category_tree/${categoryTreeId}/get_compatibility_properties`
       );
     }
   }
   
2. Add Validation Schema

   Create Zod schema for inputs:

   // src/utils/product-compatibility-schemas.ts
   import { z } from 'zod';
   
   export const getCompatibilityPropertiesSchema = z.object({
     categoryTreeId: z.string().min(1),
   });
   
3. Create Tool Definition

   Add tool in src/tools/definitions/:

   // src/tools/definitions/product-compatibility-tools.ts
   import { getCompatibilityPropertiesSchema } from '@/utils/product-compatibility-schemas.js';
   
   export const productCompatibilityTools = [
     {
       name: 'ebay_get_compatibility_properties',
       description: 'Get compatibility properties for a category',
       inputSchema: getCompatibilityPropertiesSchema,
       handler: 'productCompatibility.getCompatibilityProperties',
     },
   ];
   
4. Register in API Facade

   Add to src/api/index.ts:

   import { EbayProductCompatibilityApi } from './listing-management/product-compatibility.js';
   
   export class EbaySellerApi {
     public readonly productCompatibility: EbayProductCompatibilityApi;
   
     constructor(config: EbayConfig) {
       this.productCompatibility = new EbayProductCompatibilityApi(this.client);
     }
   }
   
5. Write Tests

   Create comprehensive tests:

   // tests/unit/api/product-compatibility.test.ts
   describe('EbayProductCompatibilityApi', () => {
     it('should get compatibility properties', async () => {
       // Test implementation
     });
   });
   
6. Update Documentation

   Document the new functionality and update API reference

Common Tasks

Updating Dependencies

# Check for outdated packages
npm outdated

# Update specific package
npm update package-name

# Update all packages (be careful)
npm update

# After updating, run tests
npm test

Generating Types from OpenAPI

When eBay updates their API specifications:

# Generate TypeScript types from OpenAPI specs
npm run generate:types

# Verify generated types
npm run typecheck

Debugging

# Run tests with debugger
node --inspect-brk ./node_modules/vitest/vitest.mjs run

# Run server in debug mode
npm run dev -- --inspect

# Enable debug logging
DEBUG=* npm run dev

Getting Help

Resources

Documentation

Browse the complete documentation

GitHub Issues

Search existing issues or create new ones

Discussions

Ask questions and share ideas

eBay Developer Portal

eBay API documentation

Communication

• Questions? Open a discussion
• Bug found? Create an issue
• Feature idea? Start a discussion

Recognition

Contributors are recognized in the following ways:

• Listed in CHANGELOG.md for their contributions
• Mentioned in release notes
• Added to GitHub contributors list
• Featured in project README

Code of Conduct

This project follows a code of conduct to ensure a welcoming and inclusive environment:

Be respectful - Treat everyone with respect and kindness

Be inclusive - Welcome newcomers and diverse perspectives

Be constructive - Provide helpful feedback and criticism

Be professional - Maintain professional standards of communication

Report unacceptable behavior to project maintainers.

License

By contributing, you agree that your contributions will be licensed under the Apache License 2.0.

Thank You!

Your contributions help make this project better for everyone. Thank you for taking the time to contribute! 🎉

Related Topics

Testing

Learn about testing standards

Architecture

Understand the system design

Error Handling

Error handling patterns

Best Practices

Development best practices