🤝 Contributing to MCP Pointer

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.

📋 Prerequisites

Before you begin, make sure you have:

Node.js 18+ installed
pnpm installed (required - see Package Manager)
Chrome browser for extension testing
Claude Code or another MCP-compatible AI tool for testing

📦 Package Manager

IMPORTANT: This project uses pnpm exclusively for dependency management. Using npm or yarn will not work due to:

Workspace configuration with catalog: dependencies
Build tooling optimized for pnpm
Team consistency and lockfile management

Install pnpm

# Via npm (if you don't have pnpm)
npm install -g pnpm

# Via Homebrew (macOS)
brew install pnpm

# Via script
curl -fsSL https://get.pnpm.io/install.sh | sh

📦 Publishing & Build Process

This project uses automated publishing via GitHub Actions with cryptographic provenance for security and transparency.

Build System

Package Manager: pnpm with workspaces
Build Tool: esbuild for fast TypeScript compilation
CLI Distribution: Single bundled .cjs file for standalone execution
Dependencies: All external packages bundled for zero-dependency installation

Publishing Workflow

Automated CI: Every push/PR runs linting, type checking, and builds
GitHub Releases: Create a release to trigger automatic npm publishing
Provenance: Cryptographically links published package to source code
Transparency: Users can verify the published CLI matches the open source code

# Create a release to publish
git tag v0.1.0
git push origin v0.1.0
# Or use GitHub's release UI

🏗 Project Structure

packages/
├── server/              # @mcp-pointer/server - MCP Server (TypeScript)
│   ├── src/
│   │   ├── start.ts      # Main server entry point
│   │   ├── cli.ts        # Command line interface
│   │   ├── message-handler.ts  # Message routing & state building
│   │   ├── services/
│   │   │   ├── websocket-service.ts      # WebSocket with leader election
│   │   │   ├── mcp-service.ts            # MCP protocol handler
│   │   │   ├── element-processor.ts      # Raw→Processed conversion
│   │   │   └── shared-state-service.ts   # State persistence
│   │   └── utils/
│   │       ├── dom-extractor.ts    # HTML parsing utilities
│   │       └── element-detail.ts   # Dynamic CSS/text filtering
│   ├── dist/
│   │   └── cli.cjs       # Bundled standalone CLI
│   └── package.json
│
├── chrome-extension/    # Chrome Extension (TypeScript)
│   ├── src/
│   │   ├── background.ts # Service worker
│   │   ├── content.ts    # Element selection
│   │   └── services/
│   │       └── element-sender-service.ts  # WebSocket client
│   ├── dev/              # Development build (with logging)
│   ├── dist/             # Production build (minified)
│   └── manifest.json
│
└── shared/             # @mcp-pointer/shared - Shared TypeScript types
    ├── src/
    │   ├── logger.ts
    │   ├── types.ts
    │   └── detail.ts   # CSS/text detail level constants
    └── package.json

🚀 Development Setup

1. Fork and Clone

# Fork the repository on GitHub, then clone your fork
git clone https://github.com/etsd-tech/mcp-pointer.git
cd mcp-pointer

# Add upstream remote
git remote add upstream https://github.com/etsd-tech/mcp-pointer.git

2. Install Dependencies

# Install all workspace dependencies
pnpm install

3. Build Everything

# Build all packages
pnpm build

🏗 Project Structure

packages/
├── server/              # @mcp-pointer/server - MCP Server (TypeScript)
│   ├── src/
│   │   ├── start.ts      # Main server entry point
│   │   ├── cli.ts        # Command line interface
│   │   ├── message-handler.ts  # Message routing & state building
│   │   ├── services/
│   │   │   ├── websocket-service.ts      # WebSocket with leader election
│   │   │   ├── mcp-service.ts            # MCP protocol handler
│   │   │   ├── element-processor.ts      # Raw→Processed conversion
│   │   │   └── shared-state-service.ts   # State persistence
│   │   └── utils/
│   │       ├── dom-extractor.ts    # HTML parsing utilities
│   │       └── element-detail.ts   # Dynamic CSS/text filtering
│   ├── dist/
│   │   └── cli.cjs       # Bundled standalone CLI
│   └── package.json
│
├── chrome-extension/    # Chrome Extension (TypeScript)
│   ├── src/
│   │   ├── background.ts # Service worker
│   │   ├── content.ts    # Element selection
│   │   └── services/
│   │       └── element-sender-service.ts  # WebSocket client
│   ├── dev/              # Development build (with logging)
│   ├── dist/             # Production build (minified)
│   └── manifest.json
│
└── shared/             # @mcp-pointer/shared - Shared TypeScript types
    ├── src/
    │   ├── logger.ts
    │   ├── types.ts
    │   └── detail.ts   # CSS/text detail level constants
    └── package.json

🏗️ System Architecture

MCP Pointer uses a distributed architecture with multiple server instances and leader election for high availability:

graph TB
    subgraph "Browser Environment"
        WEB[Web Page]
        CS[Content Script<br/>element-pointer.ts]
        BG[Background Worker<br/>background.ts]
        ES[ElementSenderService<br/>ReconnectingWebSocket]
        WEB -->|Option+Click| CS
        CS -->|Chrome Runtime API| BG
        BG -->|sendElement| ES
    end

    subgraph "MCP Server Instances"
        subgraph "Instance 1 - Leader"
            WS1[WebSocketService<br/>✅ Port 7007]
            MCP1[MCPService]
            SS1[SharedState<br/>Read/Write]
        end
        
        subgraph "Instance 2 - Follower"
            WS2[WebSocketService<br/>⏸️ Retrying...]
            MCP2[MCPService]
            SS2[SharedState<br/>Read Only]
        end
    end

    subgraph "Shared Resources"
        PORT[Port 7007<br/>First to bind wins]
        FS["/tmp/mcp-pointer-shared-state.json"]
    end

    subgraph "AI Client"
        CC[Claude Code]
    end

    ES -->|WebSocket| WS1
    WS1 -->|Owns| PORT
    WS2 -.->|Retry every 5s| PORT
    SS1 -->|Write| FS
    SS2 -->|Read| FS
    CC <-->|MCP Protocol| MCP1
    CC <-->|MCP Protocol| MCP2

    classDef leader fill:#90EE90
    classDef follower fill:#FFE4B5
    
    class WS1,SS1 leader
    class WS2,SS2 follower

How It Works

Server-Side (Multiple Instances)

Leader Election:
- Multiple MCP server instances can run simultaneously
- First instance to bind port 7007 becomes the leader
- Other instances become followers and retry every 5 seconds
- Automatic failover when leader crashes (~5 second recovery)
State Management:
- Leader instance saves element data to /tmp/mcp-pointer-shared-state.json
- All instances (leader and followers) can read shared state
- MCP requests work on any instance using shared state
Service Architecture:
- WebSocketService: Handles port-based leader election and WebSocket connections
- MCPService: Provides MCP protocol implementation for AI tools
- SharedStateService: Manages persistent element state via filesystem

Client-Side (Browser Extension)

Connection Management (ElementSenderService):
- Uses ReconnectingWebSocket library for robust WebSocket connections
- Exponential backoff: 1s min delay, 10s max delay, 1.5x grow factor
- Maximum 5 retry attempts per connection
- 5-second connection timeout
- Automatic idle disconnection after 2 minutes of inactivity
Element Selection Flow:
- Content script captures element data on Option+Click
- Data sent to background worker via Chrome Runtime API
- Background worker uses ElementSenderService to send via WebSocket
- Connection status callbacks provide user feedback (CONNECTING → CONNECTED → SENDING → SENT)
Resilience Features:
- Automatic reconnection during server restarts or leader changes
- Port change handling (disconnects old, connects to new)
- Connection status monitoring with detailed logging
- Graceful error handling with status reporting

🛠 Development Workflow

Chrome Extension Development

Build extension in development mode:

cd packages/chrome-extension
pnpm dev  # Builds to dev/ directory with logging enabled and source maps

Load extension in Chrome:
- Open Chrome → Extensions → Developer mode → Load unpacked
- Select packages/chrome-extension/dev/ folder
- The extension will appear in your browser
Making changes:
- Files are watched automatically in dev mode
- Refresh the extension in Chrome Extensions page after changes
- Check browser console for development logs
Development vs Production:
- Dev build (pnpm dev) → dev/ folder, includes logging and source maps
- Production build (pnpm build) → dist/ folder, minified, no logs

MCP Server Development

Run MCP server in watch mode:

cd packages/server
pnpm dev  # Starts server and restarts on file changes

Test server locally:

# In a separate terminal
node dist/cli.cjs --help  # Test the built CLI

Configure for development:

pnpm -C packages/server configure  # Auto-configure Claude Code

Development Commands

# Build everything for production
pnpm build

# Run linting and type checking
pnpm lint
pnpm typecheck

# Fix linting issues automatically  
pnpm lint:fix

# Clean all build outputs
pnpm -C packages/chrome-extension clean
pnpm -C packages/server clean

# Run development servers for all packages
pnpm dev

🧪 Testing

Testing Checklist

Before submitting a PR, ensure:

MCP server starts with mcp-pointer start
Chrome extension loads without errors
Option+Click highlights elements on webpages
Claude Code shows the getTargetedElement tool
Element data appears when using the tool
WebSocket connection indicator shows "Connected"
All existing tests pass
New functionality is tested

Testing Different Scenarios

Test on different websites - try React apps, Vue apps, plain HTML
Check component detection - React Fiber info should appear for React apps
Test responsive elements - resize browser and check highlighting
Verify CSS extraction - ensure styles and positions are captured
Test edge cases - very small elements, overlapping elements, etc.

Browser Testing

✅ Chrome - Primary target, test thoroughly
✅ Edge - Should work identically to Chrome
🟡 Firefox - Extension needs adaptation (contributions welcome)
🟡 Safari - Extension needs adaptation (contributions welcome)

📝 Code Style

General Guidelines

Use TypeScript for all code
Follow existing code patterns and conventions
Use esbuild for compilation (already configured)
Include JSDoc comments for public APIs
Prefer explicit types over any

Formatting

We use ESLint for code formatting and linting
Run pnpm lint:fix before committing
All code must pass pnpm typecheck

File Naming

Use kebab-case for file names: element-sender-service.ts
Use PascalCase for classes and components
Use camelCase for functions and variables

🔄 Making Changes

Branch Naming

# Feature branches
git checkout -b feature/add-firefox-support
git checkout -b feature/improve-react-detection

# Bug fix branches  
git checkout -b fix/websocket-reconnection
git checkout -b fix/element-highlighting-edge-case

# Documentation
git checkout -b docs/update-contributing-guide

Commit Messages

Use conventional commit format:

type(scope): description

Examples:
feat(extension): add Firefox support
fix(server): handle WebSocket reconnection
docs(readme): update installation instructions
refactor(shared): improve TypeScript types
test(extension): add element selection tests

Pull Request Process

Keep PRs focused - One feature or fix per PR
Update documentation - Update README or other docs if needed
Add tests - Include tests for new functionality
Check all builds pass - Ensure pnpm build works
Run quality checks:
```
pnpm lint
pnpm typecheck
pnpm build
```

PR Description Template

## Summary
Brief description of what this PR does

## Changes Made
- List key changes
- Include any breaking changes
- Mention new dependencies

## Testing
- [ ] Tested locally with Chrome extension
- [ ] Tested MCP server functionality  
- [ ] Tested with Claude Code integration
- [ ] All existing tests pass

## Screenshots (if applicable)
Include screenshots for UI changes

🐛 Troubleshooting Development Issues

Common Issues

Build failures:
- Make sure you're using pnpm, not npm/yarn
- Run pnpm install to refresh dependencies
- Check for TypeScript errors with pnpm typecheck
Extension not loading:
- Verify you built with pnpm -C packages/chrome-extension build
- Check the dist/ or dev/ folder contains files
- Reload extension in Chrome Extensions page
WebSocket connection issues:
- Ensure MCP server is running (mcp-pointer start)
- Check port 7007 is not blocked
- Look for connection errors in browser console
MCP tools not appearing in Claude Code:
- Restart Claude Code after configuration changes
- Verify .mcp.json exists and is valid
- Check MCP server logs for errors

Getting Help

Check existing GitHub Issues
Create a new issue with:
- Clear description of the problem
- Steps to reproduce
- Environment details (OS, Node version, etc.)
- Error messages or logs

📋 Release Process

This project uses Changesets for automated versioning and publishing. Contributors add changeset files to describe their changes, and maintainers manage releases through automated PRs.

Using Changesets

When you make changes that should trigger a new release, add a changeset:

# Add a changeset describing your changes
pnpm changeset

This will prompt you to:

Select packages that should be updated
Choose version bump type (patch/minor/major)
Write a summary of your changes

Example changeset session:

🦋  Which packages would you like to include?
◉ @mcp-pointer/server
◉ @mcp-pointer/shared
◯ @mcp-pointer/chrome-extension

🦋  Which packages should have a major bump?
◯ @mcp-pointer/server
◯ @mcp-pointer/shared

🦋  Which packages should have a minor bump?  
◉ @mcp-pointer/server
◯ @mcp-pointer/shared

🦋  Please enter a summary for this change
Added WebSocket connection retry logic with exponential backoff

Version Types

Patch (0.1.0 → 0.1.1): Bug fixes, small improvements
Minor (0.1.0 → 0.2.0): New features, backwards compatible
Major (0.1.0 → 1.0.0): Breaking changes

Creating a Release

For maintainers only:

Review pending changesets in .changeset/ folder
Push to main - GitHub Actions will create a "Version Packages" PR
Review the Version PR - Check version bumps and changelog
Merge the Version PR - Packages are published automatically

The automated workflow:

Creates git tags (e.g., @mcp-pointer/server@0.3.1)
Publishes to npm with provenance
Creates GitHub releases with changelogs
Handles monorepo versioning automatically

Release Workflow

graph LR
    A[Add Changeset] --> B[Push to Main]
    B --> C[Version PR Created]
    C --> D[Review & Merge PR]  
    D --> E[Auto Publish to npm]
    E --> F[Git Tags & GitHub Releases]

🎯 Contribution Ideas

Looking for ways to contribute? Here are some ideas:

🚀 Features

Firefox extension support
Safari extension support
Additional framework detection (Svelte, Angular)
Element search and filtering
Export element data to different formats
Integration with other AI tools

🐛 Bug Fixes

Improve element highlighting accuracy
Handle edge cases in component detection
WebSocket connection stability
Performance optimizations

📚 Documentation

More comprehensive examples
Video tutorials
Integration guides for different AI tools
Translation to other languages

🧪 Testing

Unit tests for core functionality
Integration tests
Cross-browser testing
Performance testing

📄 License

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

Thank you for contributing to MCP Pointer! 👆

Every contribution helps make web development with AI more powerful and accessible.

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

🤝 Contributing to MCP Pointer

📋 Prerequisites

📦 Package Manager

Install pnpm

📦 Publishing & Build Process

Build System

Publishing Workflow

🏗 Project Structure

🚀 Development Setup

1. Fork and Clone

2. Install Dependencies

3. Build Everything

🏗 Project Structure

🏗️ System Architecture

How It Works

Server-Side (Multiple Instances)

Client-Side (Browser Extension)

🛠 Development Workflow

Chrome Extension Development

MCP Server Development

Development Commands

🧪 Testing

Testing Checklist

Testing Different Scenarios

Browser Testing

📝 Code Style

General Guidelines

Formatting

File Naming

🔄 Making Changes

Branch Naming

Commit Messages

Pull Request Process

PR Description Template

🐛 Troubleshooting Development Issues

Common Issues

Getting Help

📋 Release Process

Using Changesets

Version Types

Creating a Release

Release Workflow

🎯 Contribution Ideas

🚀 Features

🐛 Bug Fixes

📚 Documentation

🧪 Testing

📄 License