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

Fork the Repository

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

Clone Your Fork

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

Install Dependencies

npm install
# or
pnpm install

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.

Build the Project

npm run build

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

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

Update Changelog

Add your changes to CHANGELOG.md:

## [Unreleased]

### Added
- Add bulk update inventory items tool (#123)

### Fixed
- Fix token refresh race condition (#124)

Push to Your Fork

git add .
git commit -m "feat: add amazing feature"
git push origin feature/amazing-feature

Create Pull Request

Go to the repository
Click “New Pull Request”
Select your fork and branch
Fill out the PR template
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

Automated Checks - CI runs tests and linting
Code Review - Maintainers review your code
Feedback - Address any requested changes
Approval - PR is approved by maintainer
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:

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`
    );
  }
}

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),
});

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',
  },
];

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);
  }
}

Write Tests

Create comprehensive tests:

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

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! 🎉

Testing

Learn about testing standards

Architecture

Understand the system design

Error Handling

Error handling patterns

Best Practices

Development best practices

Getting Started

Authentication

Core Features

Guides

MCP Integration

Advanced

Support

​Contributing

​Ways to Contribute

Bug Fixes

New Features

Documentation

Tests

Code Quality

Ideas

​Getting Started

​Prerequisites

​Development Setup

​Development Workflow

​Project Structure

​Making Changes

​Creating a Feature Branch

​Branch Naming Conventions

​Development Guidelines

​1. Code Style

​2. Writing Tests

​3. Documentation

​4. Commit Messages

​Submitting Changes

​Pull Request Process

​Pull Request Template

​Review Process

​Contribution Guidelines

​Do’s

​Don’ts

​Adding New eBay APIs

​Common Tasks

​Updating Dependencies

​Generating Types from OpenAPI

​Debugging

​Getting Help

​Resources

Documentation

GitHub Issues

Discussions

eBay Developer Portal

​Communication

​Recognition

​Code of Conduct

​License

​Thank You!

​Related Topics

Testing

Architecture

Error Handling

Best Practices

Contributing

Ways to Contribute

Getting Started

Prerequisites

Development Setup

Development Workflow

Project Structure

Making Changes

Creating a Feature Branch

Branch Naming Conventions

Development Guidelines

1. Code Style

2. Writing Tests

3. Documentation

4. Commit Messages

Submitting Changes

Pull Request Process

Pull Request Template

Review Process

Contribution Guidelines

Do’s

Don’ts

Adding New eBay APIs

Common Tasks

Updating Dependencies

Generating Types from OpenAPI

Debugging

Getting Help

Resources

Communication

Recognition

Code of Conduct

License

Thank You!

Related Topics