Chrome MCP Server

# 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** ```bash git clone https://github.com/YOUR_USERNAME/chrome-mcp-server.git cd chrome-mcp-server ``` 2. **Install dependencies** ```bash pnpm install ``` 3. **Start the project** ```bash 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`**: ```typescript { 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/`**: ```typescript 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** ```bash 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** ```bash git add . git commit -m "feat: add your feature description" ``` We use [Conventional Commits](https://www.conventionalcommits.org/): - `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** ```bash 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: ```bash 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](https://modelcontextprotocol.io/) - [Chrome Extension Development](https://developer.chrome.com/docs/extensions/) - [WXT Framework Documentation](https://wxt.dev/) - [TypeScript Handbook](https://www.typescriptlang.org/docs/) ## 🤝 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.