Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
266 lines (193 loc) · 5.19 KB

CONTRIBUTING.md

File metadata and controls

266 lines (193 loc) · 5.19 KB

Contributing to OpenCode Browser MCP Plugin

Thank you for your interest in contributing to this project! This guide will help you get started.

Ways to Contribute

  1. Report Bugs - Found an issue? Let us know!
  2. Suggest Features - Have an idea? Share it!
  3. Write Documentation - Help others understand the plugin
  4. Submit Code - Fix bugs or add features
  5. Share Examples - Add useful automation examples

Development Setup

Prerequisites

  • Node.js v18 or higher
  • OpenCode installed
  • Browser MCP extension installed
  • Git

Local Setup

  1. Clone the repository:
git clone https://github.com/michaljach/opencode-browser.git
cd opencode-browser
  1. Install dependencies (if you add any):
npm install
  1. Link the plugin locally:
# For testing
mkdir -p .opencode/plugin
ln -s $(pwd)/index.ts .opencode/plugin/browser-mcp.ts
  1. Create your OpenCode configuration:
cp opencode.json.example opencode.json

Testing Your Changes

Manual Testing

  1. Make your changes to index.ts
  2. Restart OpenCode
  3. Test with browser automation prompts
  4. Verify the changes work as expected

Test Checklist

Before submitting, ensure:

  • Plugin loads without errors
  • Basic browser navigation works
  • Tool execution hooks function correctly
  • Session context is preserved
  • No console errors or warnings
  • Documentation is updated

Code Style

TypeScript Guidelines

  • Use TypeScript for all code
  • Enable strict type checking
  • Add JSDoc comments for public APIs
  • Use meaningful variable names
  • Keep functions small and focused

Example:

/**
 * Processes browser tool execution results
 * @param input - The tool execution input
 * @param output - The tool execution output
 */
"tool.execute.after": async (input, output) => {
  if (input.tool.startsWith("browsermcp_")) {
    console.log(`Completed: ${input.tool}`)
  }
}

Submitting Changes

Pull Request Process

  1. Fork the repository
  2. Create a feature branch:
git checkout -b feature/your-feature-name
  1. Make your changes
  2. Add tests if applicable
  3. Update documentation
  4. Commit with a clear message:
git commit -m "feat: add custom browser tool for screenshots"
  1. Push to your fork:
git push origin feature/your-feature-name
  1. Open a Pull Request

Commit Message Format

Use conventional commits:

  • feat: - New feature
  • fix: - Bug fix
  • docs: - Documentation changes
  • refactor: - Code refactoring
  • test: - Adding tests
  • chore: - Maintenance tasks

Examples:

feat: add screenshot comparison tool
fix: resolve session context preservation issue
docs: update installation instructions for Windows

Adding New Features

Custom Tools

To add a custom browser tool:

return {
  tool: {
    browser_screenshot: tool({
      description: "Take a screenshot of the current page",
      args: {
        fullPage: tool.schema.boolean().optional(),
      },
      async execute(args, ctx) {
        // Implementation
        return "Screenshot saved"
      },
    }),
  },
}

New Hooks

To add a new hook:

return {
  "new.hook.name": async (input, output) => {
    // Implementation
  },
}

Documentation Standards

README.md Structure

  • Clear, concise explanations
  • Code examples for all features
  • Troubleshooting section
  • Links to related resources

Code Comments

  • Explain WHY, not WHAT
  • Use JSDoc for public APIs
  • Keep comments up-to-date

Examples

Add practical examples to EXAMPLES.md:

## Your Feature Name

### Use Case Description

Your example prompt here


Explanation of what happens.

Review Process

What We Look For

  1. Functionality - Does it work as intended?
  2. Code Quality - Is it well-written and maintainable?
  3. Documentation - Is it properly documented?
  4. Tests - Are edge cases handled?
  5. Breaking Changes - Are they necessary and documented?

Response Time

  • We aim to review PRs within 3-5 days
  • Complex changes may take longer
  • Feel free to ping if no response after a week

Getting Help

Questions?

  • Check existing issues and discussions
  • Review the documentation
  • Ask in the PR or issue comments
  • Join the OpenCode Discord (if available)

Resources

Community Guidelines

Be Respectful

  • Treat everyone with respect
  • Assume good intentions
  • Provide constructive feedback
  • Help others learn and grow

Be Professional

  • Keep discussions on-topic
  • Avoid inflammatory language
  • Respect different perspectives
  • Follow the code of conduct

Recognition

Contributors will be:

  • Listed in the README
  • Credited in release notes
  • Appreciated by the community

License

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

Questions?

Feel free to open an issue or discussion if you have questions about contributing!

Thank you for contributing to OpenCode Browser MCP Plugin!