Contributing Guide 🤝

Thank you for your interest in contributing to Chrome MCP Server! This document provides guidelines and information for contributors.

🎯 How to Contribute

We welcome contributions in many forms:

• 🐛 Bug reports and fixes
• ✨ New features and tools
• 📚 Documentation improvements
• 🧪 Tests and performance optimizations
• 🌐 Translations and internationalization
• 💡 Ideas and suggestions

🚀 Getting Started

Prerequisites

• Node.js 18.19.0+ and pnpm or npm (latest version)
• Chrome/Chromium browser for testing
• Git for version control
• Rust (for WASM development, optional)
• TypeScript knowledge

Development Setup

1. Fork and clone the repository

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

2. Install dependencies

pnpm install

3. Start the project

npm run dev

4. Load the extension in Chrome
   • Open chrome://extensions/
   • Enable "Developer mode"
   • Click "Load unpacked" and select your/extension/dist

🏗️ Project Structure

chrome-mcp-server/
├── app/
│   ├── chrome-extension/     # Chrome extension (WXT + Vue 3)
│   │   ├── entrypoints/      # Background scripts, popup, content scripts
│   │   ├── utils/            # AI models, vector database, utilities
│   │   └── workers/          # Web Workers for AI processing
│   └── native-server/        # Native messaging server (Fastify + TypeScript)
│       ├── src/mcp/          # MCP protocol implementation
│       └── src/server/       # HTTP server and native messaging
├── packages/
│   ├── shared/               # Shared types and utilities
│   └── wasm-simd/           # SIMD-optimized WebAssembly math functions
└── docs/                    # Documentation

🛠️ Development Workflow

Adding New Tools

1. Define the tool schema in packages/shared/src/tools.ts:

{
  name: 'your_new_tool',
  description: 'Description of what your tool does',
  inputSchema: {
    type: 'object',
    properties: {
      // Define parameters
    },
    required: ['param1']
  }
}

2. Implement the tool in app/chrome-extension/entrypoints/background/tools/browser/:

class YourNewTool extends BaseBrowserToolExecutor {
  name = TOOL_NAMES.BROWSER.YOUR_NEW_TOOL;

  async execute(args: YourToolParams): Promise<ToolResult> {
    // Implementation
  }
}

3. Export the tool in app/chrome-extension/entrypoints/background/tools/browser/index.ts

4. Add tests in the appropriate test directory

Code Style Guidelines

• TypeScript: Use strict TypeScript with proper typing
• ESLint: Follow the configured ESLint rules (pnpm lint)
• Prettier: Format code with Prettier (pnpm format)
• Naming: Use descriptive names and follow existing patterns
• Comments: Add JSDoc comments for public APIs
• Error Handling: Always handle errors gracefully

📝 Pull Request Process

1. Create a feature branch

git checkout -b feature/your-feature-name

2. Make your changes

   • Follow the code style guidelines
   • Add tests for new functionality
   • Update documentation if needed

3. Test your changes

   • Ensure all existing tests pass
   • Test the Chrome extension manually
   • Verify MCP protocol compatibility

4. Commit your changes

git add .
git commit -m "feat: add your feature description"

We use Conventional Commits:

• feat: for new features
• fix: for bug fixes
• docs: for documentation changes
• test: for adding tests
• refactor: for code refactoring

5. Push and create a Pull Request

git push origin feature/your-feature-name

🐛 Bug Reports

When reporting bugs, please include:

• Environment: OS, Chrome version, Node.js version
• Steps to reproduce: Clear, step-by-step instructions
• Expected behavior: What should happen
• Actual behavior: What actually happens
• Screenshots/logs: If applicable
• MCP client: Which MCP client you're using (Claude Desktop, etc.)

💡 Feature Requests

For feature requests, please provide:

• Use case: Why is this feature needed?
• Proposed solution: How should it work?
• Alternatives: Any alternative solutions considered?
• Additional context: Screenshots, examples, etc.

🔧 Development Tips

Using WASM SIMD

If you're contributing to the WASM SIMD package:

cd packages/wasm-simd
# Install Rust and wasm-pack if not already installed
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
cargo install wasm-pack

# Build WASM package
pnpm build

# The built files will be copied to app/chrome-extension/workers/

Debugging Chrome Extension

• Use Chrome DevTools for debugging extension popup and background scripts
• Check chrome://extensions/ for extension errors
• Use console.log statements for debugging
• Monitor the native messaging connection in the background script

Testing MCP Protocol

• Use MCP Inspector for protocol debugging
• Test with different MCP clients (Claude Desktop, custom clients)
• Verify tool schemas and responses match MCP specifications

📚 Resources

• Model Context Protocol Specification
• Chrome Extension Development
• WXT Framework Documentation
• TypeScript Handbook

🤝 Community

• GitHub Issues: For bug reports and feature requests
• GitHub Discussions: For questions and general discussion
• Pull Requests: For code contributions

📄 License

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

🎯 Contributor Guidelines

New Contributors

If you're contributing to an open source project for the first time:

1. Start small: Look for issues labeled "good first issue"
2. Read the code: Familiarize yourself with the project structure and coding style
3. Ask questions: Ask questions in GitHub Discussions
4. Learn the tools: Get familiar with Git, GitHub, TypeScript, and other tools

Experienced Contributors

• Architecture improvements: Propose system-level improvements
• Performance optimization: Identify and fix performance bottlenecks
• New features: Design and implement complex new features
• Mentor newcomers: Help new contributors get started

Documentation Contributions

• API documentation: Improve tool documentation and examples
• Tutorials: Create usage guides and best practices
• Translations: Help translate documentation to other languages
• Video content: Create demo videos and tutorials

Testing Contributions

• Unit tests: Write tests for new features
• Integration tests: Test interactions between components
• Performance tests: Benchmark testing and performance regression detection
• User testing: Functional testing in real-world scenarios

🏆 Contributor Recognition

We value every contribution, no matter how big or small. Contributors will be recognized in the following ways:

• README acknowledgments: Contributors listed in the project README
• Release notes: Contributors thanked in version release notes
• Contributor badges: Contributor badges on GitHub profiles
• Community recognition: Special thanks in community discussions

Thank you for considering contributing to Chrome MCP Server! Your participation makes this project better.