browser-x-mcp/docs/CONTRIBUTING.md

AI-Powered Browser Automation with Advanced Form Testing - A Model Context Provider (MCP) server that enables intelligent browser automation with form testing, element extraction, and comprehensive logging

# 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

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

# Install dependencies
npm install

# 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

```bash
npm run lint
npm run lint:fix
```

## Testing

### Running Tests

```bash
# Run all tests
npm test

# Run AI tests
npm run test:ai:mcp

# Run mock tests
npm run test:mock

# Run real website tests
npm run test:real-websites
```

### 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:
```javascript
/**
 * 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! 🚀