SF Express MCP Server

# Contributing to SF Express MCP Server Thank you for your interest in contributing to the SF Express MCP Server! This document provides guidelines and information for contributors. ## Getting Started ### Prerequisites - Node.js 18.0.0 or higher - npm or yarn package manager - Git - SF Express developer account (for testing) ### Setup 1. Fork the repository on GitHub 2. Clone your fork locally: ```bash git clone https://github.com/YOUR_USERNAME/sf-express-mcp.git cd sf-express-mcp ``` 3. Install dependencies: ```bash npm install ``` 4. Copy the environment template: ```bash cp .env.example .env ``` 5. Fill in your SF Express API credentials in `.env` ## Development Process ### Branch Naming - Feature branches: `feature/description-of-feature` - Bug fixes: `fix/description-of-bug` - Documentation: `docs/description-of-change` ### Coding Standards - Use TypeScript for all new code - Follow existing code style and formatting - Add type definitions for all functions and variables - Use meaningful variable and function names - Add JSDoc comments for public APIs ### Testing Before submitting a pull request: 1. Run the linter: ```bash npm run lint ``` 2. Build the project: ```bash npm run build ``` 3. Test the server manually: ```bash npm run dev ``` ### Commit Messages Use clear, descriptive commit messages: - Use the imperative mood ("Add feature" not "Added feature") - First line should be 50 characters or less - Reference issues and pull requests when applicable Examples: ``` Add support for bulk shipment tracking Fix authentication error handling Update README with new installation steps ``` ## Types of Contributions ### Bug Reports When reporting bugs, please include: - Clear description of the issue - Steps to reproduce - Expected vs actual behavior - Environment details (Node.js version, OS, etc.) - Error messages or logs ### Feature Requests For new features, please: - Check if the feature already exists or is planned - Describe the use case and benefit - Consider backward compatibility - Propose an implementation approach ### Code Contributions #### Adding New SF Express APIs When adding support for new SF Express APIs: 1. Create a new tool file in `src/tools/` 2. Define appropriate TypeScript types in `src/types.ts` 3. Add the API method to `src/sf-express-client.ts` 4. Register the tool in `src/index.ts` 5. Update the README with documentation 6. Test with real API credentials #### Improving Existing Features - Maintain backward compatibility - Update relevant documentation - Consider error handling improvements - Add appropriate logging ## Pull Request Process 1. Create a feature branch from `main` 2. Make your changes following the coding standards 3. Test your changes thoroughly 4. Update documentation as needed 5. Create a pull request with: - Clear title and description - Reference to related issues - Summary of changes made - Testing instructions ### Pull Request Review All pull requests require review before merging. Reviews will check for: - Code quality and style - Functionality and correctness - Documentation completeness - Test coverage - Security considerations ## Security If you discover a security vulnerability, please: 1. **Do not** open a public issue 2. Email the maintainers privately 3. Provide detailed information about the vulnerability 4. Wait for confirmation before disclosing publicly ## API Guidelines ### SF Express API Integration - Always validate input parameters using Zod schemas - Implement proper error handling and user-friendly error messages - Follow SF Express API documentation exactly - Include appropriate timeouts and retry logic - Log API interactions for debugging (without sensitive data) ### MCP Tool Implementation - Follow MCP protocol specifications - Provide clear tool descriptions and parameter schemas - Return structured, consistent responses - Handle edge cases gracefully - Include comprehensive error information ## Documentation - Update README.md for user-facing changes - Add inline code comments for complex logic - Include examples for new features - Keep API documentation current ## Questions and Support - Check existing issues before creating new ones - Use GitHub Discussions for questions and ideas - Tag maintainers for urgent issues ## License By contributing to this project, you agree that your contributions will be licensed under the MIT License. ## Recognition Contributors will be recognized in the project's README and release notes. Thank you for contributing to the SF Express MCP Server!