266 lines
7.6 KiB
Markdown
266 lines
7.6 KiB
Markdown
# 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.
|