Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
233 lines (172 loc) · 5.11 KB

CONTRIBUTING.md

File metadata and controls

233 lines (172 loc) · 5.11 KB
Raw

Contributing to Browser[X]MCP

We love your input! We want to make contributing to Browser[X]MCP as easy and transparent as possible, whether it's:

  • Reporting a bug
  • Discussing the current state of the code
  • Submitting a fix
  • Proposing new features
  • Becoming a maintainer

Development Process

We use GitHub to host code, to track issues and feature requests, as well as accept pull requests.

Pull Requests

  1. Fork the repo and create your branch from main.
  2. If you've added code that should be tested, add tests.
  3. If you've changed APIs, update the documentation.
  4. Ensure the test suite passes.
  5. Make sure your code lints.
  6. Issue that pull request!

Development Setup

# Fork and clone the repository
git clone https://github.com/yourusername/browserx-mcp.git
cd browserx-mcp

# Install dependencies
npm install

# Install Playwright browser binaries for local browser tests
npx playwright install chromium

# Run tests to verify setup
npm test

# Start development server
npm run dev

Code Style

  • Use ES6+ features where appropriate
  • Follow existing code style and patterns
  • Add JSDoc comments for public APIs
  • Use meaningful variable and function names
  • Keep functions small and focused

Linting

npm run lint
npm run lint:fix

Testing

Running Tests

# Run all tests
npm test

# Run AI tests
npm run test:ai

# Run mock tests
npm run test:mock

# Generate a report
npm run test:report

Writing Tests

  • Add tests for new features
  • Update tests when changing existing functionality
  • Use descriptive test names
  • Test both success and error cases

Project Structure

browserx-mcp/
├── src/
│   ├── server/              # MCP Server implementation
│   │   ├── index.js         # Main server
│   │   ├── atomic-navigation.js
│   │   └── daemon.js
│   └── extractor/           # Page analysis
│       └── VirtualCanvasExtractor.js
├── test/                    # Test files
├── tools/                   # Development tools
├── examples/                # Usage examples
├── docs/                    # Documentation
└── config/                  # Configuration

Feature Development

Adding New MCP Methods

  1. Add method to src/server/index.js
  2. Follow existing patterns for error handling
  3. Add comprehensive JSDoc documentation
  4. Write tests for the new method
  5. Update API documentation

Example:

/**
 * New MCP method description
 * @param {Object} args - Method arguments
 * @returns {Promise<Object>} MCP response
 */
async newMethod(args) {
    try {
        // Implementation
        return {
            content: [{ type: 'text', text: 'Success' }]
        };
    } catch (error) {
        throw new Error(`Method failed: ${error.message}`);
    }
}

Adding AI Capabilities

  1. Enhance test/ai-mcp-interaction-test.js
  2. Add new decision types if needed
  3. Update AI prompts and validation
  4. Test with different AI models
  5. Document new capabilities

Bug Reports

We use GitHub issues to track public bugs. Report a bug by opening a new issue.

Great Bug Reports include:

  • A quick summary and/or background
  • Steps to reproduce
  • What you expected would happen
  • What actually happens
  • Notes (possibly including why you think this might be happening)

Feature Requests

We welcome feature requests! Please:

  1. Check if the feature already exists
  2. Explain the problem you're trying to solve
  3. Provide examples of how you'd use the feature
  4. Consider the scope and complexity

Documentation

Types of Documentation

  • API Documentation: JSDoc comments in code
  • User Guides: docs/ directory
  • Examples: examples/ directory
  • README: Main project overview

Writing Good Documentation

  • Use clear, simple language
  • Provide practical examples
  • Keep documentation up to date with code changes
  • Include troubleshooting sections

Roadmap Contributions

We have an active roadmap with planned features:

High Priority

  • Screenshot analyzer tool
  • Enhanced error handling
  • Performance optimization
  • Multi-browser support

Medium Priority

  • Visual testing framework
  • Cloud deployment options
  • Enterprise features
  • Mobile browser automation

Low Priority

  • Additional AI model support
  • Advanced analytics
  • Plugin system
  • Custom extractors

Community Guidelines

Code of Conduct

  • Be respectful and inclusive
  • Focus on constructive feedback
  • Help others learn and grow
  • Maintain professional communication

Getting Help

  • Check existing documentation
  • Search through GitHub issues
  • Ask questions in discussions
  • Join our community channels

Recognition

Contributors will be recognized in:

  • README contributors section
  • Release notes for significant contributions
  • GitHub contributor graphs
  • Special mention for major features

License

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

Questions?

Don't hesitate to reach out:

  • Open a GitHub issue
  • Start a discussion
  • Contact maintainers directly

Thank you for contributing to Browser[X]MCP! 🚀