Skip to content

Commit 13e8596

Browse files
elieteyssedouelieteyssedou
committed
Add contribution guide
1 parent b9bcb95 commit 13e8596

File tree

1 file changed

+362
-0
lines changed

1 file changed

+362
-0
lines changed

‎CONTRIBUTING.md‎

Lines changed: 362 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,362 @@
1+
# 🤝 Contributing to MCP Pointer
2+
3+
Thank you for your interest in contributing to MCP Pointer! This guide will help you set up your development environment and understand our contribution process.
4+
5+
## 📋 Prerequisites
6+
7+
Before you begin, make sure you have:
8+
9+
- **Node.js** 18+ installed
10+
- **pnpm** installed (required - see [Package Manager](#package-manager))
11+
- **Chrome** browser for extension testing
12+
- **Claude Code** or another MCP-compatible AI tool for testing
13+
14+
## 📦 Package Manager
15+
16+
**IMPORTANT**: This project uses **pnpm** exclusively for dependency management. Using npm or yarn will not work due to:
17+
18+
- Workspace configuration with `catalog:` dependencies
19+
- Build tooling optimized for pnpm
20+
- Team consistency and lockfile management
21+
22+
### Install pnpm
23+
24+
```bash
25+
# Via npm (if you don't have pnpm)
26+
npm install -g pnpm
27+
28+
# Via Homebrew (macOS)
29+
brew install pnpm
30+
31+
# Via script
32+
curl -fsSL https://get.pnpm.io/install.sh | sh
33+
```
34+
35+
## 🚀 Development Setup
36+
37+
### 1. Fork and Clone
38+
39+
```bash
40+
# Fork the repository on GitHub, then clone your fork
41+
git clone https://github.com/elieteyssedou/mcp-pointer.git
42+
cd mcp-pointer
43+
44+
# Add upstream remote
45+
git remote add upstream https://github.com/elieteyssedou/mcp-pointer.git
46+
```
47+
48+
### 2. Install Dependencies
49+
50+
```bash
51+
# Install all workspace dependencies
52+
pnpm install
53+
```
54+
55+
### 3. Build Everything
56+
57+
```bash
58+
# Build all packages
59+
pnpm build
60+
```
61+
62+
## 🏗 Project Structure
63+
64+
```
65+
packages/
66+
├── server/ # @mcp-pointer/server - MCP Server (TypeScript)
67+
│ ├── src/
68+
│ │ ├── start.ts # Main server entry point
69+
│ │ ├── cli.ts # Command line interface
70+
│ │ ├── websocket-server.ts
71+
│ │ └── mcp-handler.ts
72+
│ ├── dist/
73+
│ │ └── cli.cjs # Bundled standalone CLI
74+
│ └── package.json
75+
│
76+
├── chrome-extension/ # Chrome Extension (TypeScript)
77+
│ ├── src/
78+
│ │ ├── background.ts # Service worker
79+
│ │ ├── content.ts # Element selection
80+
│ │ └── element-sender-service.ts
81+
│ ├── dev/ # Development build (with logging)
82+
│ ├── dist/ # Production build (minified)
83+
│ └── manifest.json
84+
│
85+
└── shared/ # @mcp-pointer/shared - Shared TypeScript types
86+
├── src/
87+
│ ├── Logger.ts
88+
│ └── types.ts
89+
└── package.json
90+
```
91+
92+
## 🛠 Development Workflow
93+
94+
### Chrome Extension Development
95+
96+
1. **Build extension in development mode**:
97+
```bash
98+
cd packages/chrome-extension
99+
pnpm dev # Builds to dev/ directory with logging enabled and source maps
100+
```
101+
102+
2. **Load extension in Chrome**:
103+
- Open Chrome → Extensions → Developer mode → Load unpacked
104+
- Select `packages/chrome-extension/dev/` folder
105+
- The extension will appear in your browser
106+
107+
3. **Making changes**:
108+
- Files are watched automatically in dev mode
109+
- Refresh the extension in Chrome Extensions page after changes
110+
- Check browser console for development logs
111+
112+
4. **Development vs Production**:
113+
- **Dev build** (`pnpm dev`) → `dev/` folder, includes logging and source maps
114+
- **Production build** (`pnpm build`) → `dist/` folder, minified, no logs
115+
116+
### MCP Server Development
117+
118+
1. **Run MCP server in watch mode**:
119+
```bash
120+
cd packages/server
121+
pnpm dev # Starts server and restarts on file changes
122+
```
123+
124+
2. **Test server locally**:
125+
```bash
126+
# In a separate terminal
127+
node dist/cli.cjs --help # Test the built CLI
128+
```
129+
130+
3. **Configure for development**:
131+
```bash
132+
pnpm -C packages/server configure # Auto-configure Claude Code
133+
```
134+
135+
### Development Commands
136+
137+
```bash
138+
# Build everything for production
139+
pnpm build
140+
141+
# Run linting and type checking
142+
pnpm lint
143+
pnpm typecheck
144+
145+
# Fix linting issues automatically
146+
pnpm lint:fix
147+
148+
# Clean all build outputs
149+
pnpm -C packages/chrome-extension clean
150+
pnpm -C packages/server clean
151+
152+
# Run development servers for all packages
153+
pnpm dev
154+
```
155+
156+
## 🧪 Testing
157+
158+
### Testing Checklist
159+
160+
Before submitting a PR, ensure:
161+
162+
- [ ] MCP server starts with `mcp-pointer start`
163+
- [ ] Chrome extension loads without errors
164+
- [ ] Option+Click highlights elements on webpages
165+
- [ ] Claude Code shows the `getTargetedElement` tool
166+
- [ ] Element data appears when using the tool
167+
- [ ] WebSocket connection indicator shows "Connected"
168+
- [ ] All existing tests pass
169+
- [ ] New functionality is tested
170+
171+
### Testing Different Scenarios
172+
173+
1. **Test on different websites** - try React apps, Vue apps, plain HTML
174+
2. **Check component detection** - React Fiber info should appear for React apps
175+
3. **Test responsive elements** - resize browser and check highlighting
176+
4. **Verify CSS extraction** - ensure styles and positions are captured
177+
5. **Test edge cases** - very small elements, overlapping elements, etc.
178+
179+
### Browser Testing
180+
181+
- ✅ **Chrome** - Primary target, test thoroughly
182+
- ✅ **Edge** - Should work identically to Chrome
183+
- 🟡 **Firefox** - Extension needs adaptation (contributions welcome)
184+
- 🟡 **Safari** - Extension needs adaptation (contributions welcome)
185+
186+
## 📝 Code Style
187+
188+
### General Guidelines
189+
190+
- Use **TypeScript** for all code
191+
- Follow existing code patterns and conventions
192+
- Use **esbuild** for compilation (already configured)
193+
- Include JSDoc comments for public APIs
194+
- Prefer explicit types over `any`
195+
196+
### Formatting
197+
198+
- We use **ESLint** for code formatting and linting
199+
- Run `pnpm lint:fix` before committing
200+
- All code must pass `pnpm typecheck`
201+
202+
### File Naming
203+
204+
- Use **kebab-case** for file names: `element-sender-service.ts`
205+
- Use **PascalCase** for classes and components
206+
- Use **camelCase** for functions and variables
207+
208+
## 🔄 Making Changes
209+
210+
### Branch Naming
211+
212+
```bash
213+
# Feature branches
214+
git checkout -b feature/add-firefox-support
215+
git checkout -b feature/improve-react-detection
216+
217+
# Bug fix branches
218+
git checkout -b fix/websocket-reconnection
219+
git checkout -b fix/element-highlighting-edge-case
220+
221+
# Documentation
222+
git checkout -b docs/update-contributing-guide
223+
```
224+
225+
### Commit Messages
226+
227+
Use conventional commit format:
228+
229+
```
230+
type(scope): description
231+
232+
Examples:
233+
feat(extension): add Firefox support
234+
fix(server): handle WebSocket reconnection
235+
docs(readme): update installation instructions
236+
refactor(shared): improve TypeScript types
237+
test(extension): add element selection tests
238+
```
239+
240+
### Pull Request Process
241+
242+
1. **Keep PRs focused** - One feature or fix per PR
243+
2. **Update documentation** - Update README or other docs if needed
244+
3. **Add tests** - Include tests for new functionality
245+
4. **Check all builds pass** - Ensure `pnpm build` works
246+
5. **Run quality checks**:
247+
```bash
248+
pnpm lint
249+
pnpm typecheck
250+
pnpm build
251+
```
252+
253+
### PR Description Template
254+
255+
```markdown
256+
## Summary
257+
Brief description of what this PR does
258+
259+
## Changes Made
260+
- List key changes
261+
- Include any breaking changes
262+
- Mention new dependencies
263+
264+
## Testing
265+
- [ ] Tested locally with Chrome extension
266+
- [ ] Tested MCP server functionality
267+
- [ ] Tested with Claude Code integration
268+
- [ ] All existing tests pass
269+
270+
## Screenshots (if applicable)
271+
Include screenshots for UI changes
272+
```
273+
274+
## 🐛 Troubleshooting Development Issues
275+
276+
### Common Issues
277+
278+
1. **Build failures**:
279+
- Make sure you're using pnpm, not npm/yarn
280+
- Run `pnpm install` to refresh dependencies
281+
- Check for TypeScript errors with `pnpm typecheck`
282+
283+
2. **Extension not loading**:
284+
- Verify you built with `pnpm -C packages/chrome-extension build`
285+
- Check the `dist/` or `dev/` folder contains files
286+
- Reload extension in Chrome Extensions page
287+
288+
3. **WebSocket connection issues**:
289+
- Ensure MCP server is running (`mcp-pointer start`)
290+
- Check port 7007 is not blocked
291+
- Look for connection errors in browser console
292+
293+
4. **MCP tools not appearing in Claude Code**:
294+
- Restart Claude Code after configuration changes
295+
- Verify `.mcp.json` exists and is valid
296+
- Check MCP server logs for errors
297+
298+
### Getting Help
299+
300+
- Check existing [GitHub Issues](https://github.com/elieteyssedou/mcp-pointer/issues)
301+
- Create a new issue with:
302+
- Clear description of the problem
303+
- Steps to reproduce
304+
- Environment details (OS, Node version, etc.)
305+
- Error messages or logs
306+
307+
## 📋 Release Process
308+
309+
This project uses automated publishing:
310+
311+
1. **Create a PR** with your changes
312+
2. **Get it reviewed** and merged
313+
3. **Create a release** on GitHub to trigger publishing
314+
4. **Automated CI** handles building and npm publishing
315+
316+
For maintainers only:
317+
```bash
318+
# Create a release
319+
git tag v0.2.0
320+
git push origin v0.2.0
321+
# Or use GitHub's release UI
322+
```
323+
324+
## 🎯 Contribution Ideas
325+
326+
Looking for ways to contribute? Here are some ideas:
327+
328+
### 🚀 Features
329+
- Firefox extension support
330+
- Safari extension support
331+
- Additional framework detection (Svelte, Angular)
332+
- Element search and filtering
333+
- Export element data to different formats
334+
- Integration with other AI tools
335+
336+
### 🐛 Bug Fixes
337+
- Improve element highlighting accuracy
338+
- Handle edge cases in component detection
339+
- WebSocket connection stability
340+
- Performance optimizations
341+
342+
### 📚 Documentation
343+
- More comprehensive examples
344+
- Video tutorials
345+
- Integration guides for different AI tools
346+
- Translation to other languages
347+
348+
### 🧪 Testing
349+
- Unit tests for core functionality
350+
- Integration tests
351+
- Cross-browser testing
352+
- Performance testing
353+
354+
## 📄 License
355+
356+
By contributing to MCP Pointer, you agree that your contributions will be licensed under the MIT License.
357+
358+
---
359+
360+
**Thank you for contributing to MCP Pointer! 👆**
361+
362+
Every contribution helps make web development with AI more powerful and accessible.

0 commit comments

Comments
 (0)