Content
# web-element-picker
> **AI-powered Frontend Development with Precise Element Selection**
**Version**: 1.5.0 | **License**: MIT
---
## 🎯 Quick Start
Element Picker allows you to select page elements in the browser with a click, and AI automatically obtains the precise source code location for modification.
**Core Process**:
1. Select elements in the browser → Generate a unique ID (`mcp_elp:XXX` format)
2. Copy the ID (automatically adds `#` prefix) → `#mcp_elp:067842_a7k9m2`
3. AI recognizes the ID → Automatically calls MCP tool → Gets source code location → Precise modification
**Supported AI Tools**: Cursor, Cline, Claude Desktop, Roo Code, and all tools supporting the MCP protocol
### 📖 Full Documentation
- **[User Manual](./docs/User Manual.md)** - Detailed usage guide
- **[Development and Maintenance Manual](./docs/Development and Maintenance Manual.md)** - Technical documentation and maintenance guide
---
## ✨ Core Features
- 🎯 **Floating Control Panel** - Resident on the browser right side, no need to click the extension icon
- 🔄 **Continuous Multi-Selection** - Select multiple elements at once, batch submission
- 🆔 **AI-Friendly ID** - Format `mcp_elp:XXX`, automatically adds `#` prefix when copying
- 📦 **Session Management** - Organize related elements into a single session
- 📋 **Full Functionality** - Copy, view, highlight, delete
- 🌐 **Offline Priority** - Fully available offline, local storage priority
- ⚡ **On-Demand Sync** - Immediate sync when user operates, no background timer
- 🎨 **Precise Conversation** - Use `#mcp_elp:XXX` to precisely specify elements
- 📦 **NPM Release** - Support npx one-click integration, no need for local build
- 💾 **Atomic Storage** - Write-then-rename ensures data integrity
- 🚀 **Smart Port** - Automatically find available ports (54721-54725)
- 🔄 **Port Self-Healing** - Automatically clean up orphaned processes at startup, ports always reused
- 🤝 **Multi-Agent Support** - Cursor, Cline, Claude can be used simultaneously
- 🔄 **Automatic Degradation** - Downgrade to memory mode when permission issues occur
- ✅ **Integrity Verification** - Automatically verify data structure when reading
- 🔗 **Cross-Tool Sharing** - Cline, Roo Code, Cursor data consistency
---
## 💡 ID Format Description
### Why `mcp_elp:XXX` format?
**Design Considerations**:
- `mcp_` - Clearly identify as related to MCP tools
- `elp` - Abbreviation for Element Picker
- `:` - Separator, similar to CSS selectors, improves readability
- Example: `mcp_elp:067842_a7k9m2` (21 characters)
**Automatically adds `#` prefix when copying**:
- Copy result: `#mcp_elp:067842_a7k9m2`
- Makes AI easier to recognize as an Element Picker reference
- Complies with common reference patterns (e.g., CSS `#id`, Markdown `#title`)
- MCP tools automatically remove `#` prefix for lookup
**Robustness Guarantee**:
- Regular expression verification: `^mcp_elp:[0-9]{6}_[a-z0-9]{6}$`
- Automatic cleanup: Remove `#`, remove spaces
- Error handling: Supports various variations like `#mcp_elp:XXX`, `##mcp_elp:XXX`, ` #mcp_elp:XXX `
---
## 📦 Quick Installation
### Method 1: Install from NPM (Recommended, available after release)
```bash
# 1. Install browser extension
npm install
npm run build:extension
# 2. Load extension to browser
# - Open chrome://extensions/
# - Enable "Developer mode"
# - Load packages/browser-extension/dist
# 3. Configure MCP (no local build required)
```
**Cursor/Cline Configuration**:
Windows:
```json
{
"mcpServers": {
"web-element-picker-mcp": {
"command": "cmd",
"args": ["/c", "npx", "-y", "web-element-picker-mcp"]
}
}
}
```
macOS/Linux:
```json
{
"mcpServers": {
"web-element-picker-mcp": {
"command": "npx",
"args": ["-y", "web-element-picker-mcp"]
}
}
}
```
✅ **Advantages**: No path configuration required, automatic updates, cross-platform compatibility
### Method 2: Local Development Installation
```bash
# 1. Build all packages
npm install
npm run build
# 2. Load extension (same as above)
# 3. Configure MCP (local path)
```
**Configuration File**: `%APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
```json
{
"mcpServers": {
"web-element-picker-mcp": {
"command": "node",
"args": ["C:\\full path\\packages\\mcp-server\\bin\\mcp-server.js"]
}
}
}
```
**Complete!** 🎉
---
## 🚀 Basic Usage
1. Click the "Start Selecting" button on the floating panel (or click the extension icon)
2. Click the page element to modify (can click multiple elements continuously)
3. Click "✅ Confirm" to save selection
4. Click 📋 to copy element ID (automatically copied as `#mcp_elp:XXX` format)
5. In AI conversation: `#mcp_elp:XXX` change to blue
6. AI automatically recognizes and calls MCP tool, precisely modifies source code ✨
---
## 🏗️ Project Structure
```
web-element-picker/
├── packages/
│ ├── browser-extension/ # Browser extension
│ └── mcp-server/ # MCP server (port: 54721-54725)
├── scripts/ # Build scripts
├── examples/ # Example applications
├── docs/ # Documentation directory
│ ├── User Manual.md
│ └── Development and Maintenance Manual.md
└── README.md # This file
```
---
## 📊 Performance
| Metric | Value |
|------|------|
| Memory usage | ~300 KB |
| CPU usage | <1% |
| Operation response | Instant |
| Sync method | On-demand sync (no delay) |
| Port discovery | First <200ms, cache hit <10ms |
---
## 📝 Changelog
### v1.5.0 (2026-01-27)
**Precise Element Positioning Optimization**:
- ✅ Refactored `highlightBySelection()` - Implemented multi-level positioning strategy
- ✅ Added four-level positioning priority - Memory cache → Unique identifier → CSS filtering → XPath filtering
- ✅ Enhanced dual protection mechanism - Inner layer filtering + Outer layer verification
- ✅ Fixed multiple identical component positioning errors - Precisely distinguished through position and attributes
- ✅ Improved data consistency - elementRegistry and DOM elements fully synchronized
### v1.4.0 (2026-01-26)
**Architecture Upgrade**:
- ✅ Added Background Script HTTP proxy - Solved CSP restrictions
- ✅ Optimized port cache - Persistent storage, Service Worker security
- ✅ Enhanced request deduplication and timeout protection
### v1.3.0 (2026-01-24)
**Hash Route Support**:
- ✅ Intelligent route recognition - Supports both Hash and History modes
- ✅ Precise element positioning enhancement - pageContext, componentInstance, visualPosition
### v1.2.3 (2026-01-23)
**Port Self-Healing Function**:
- ✅ Automatically detects and cleans up orphaned processes at startup
- ✅ Port isolation PID file, supports multiple agents used simultaneously
See detailed update records in [CHANGELOG.md](./CHANGELOG.md)
---
## 🛠️ Port Management
### Port Self-Healing Function (v1.2.3+)
**No manual cleanup required!** 🎉
Starting from v1.2.3, MCP server has port self-healing capability:
- ✅ Automatically detects and cleans up orphaned processes at startup
- ✅ Ports always reused, not incremented
- ✅ Supports multiple AI tools used simultaneously
**Working Principle**:
1. Each port has an independent PID file (`~/.element-picker/port-54721.pid`)
2. Checks PID file at startup, automatically cleans up if process has died
3. Multiple agents occupy different ports, do not interfere with each other
### Manual Cleanup (only needed in extreme cases)
If you encounter extreme situations requiring manual cleanup, use:
```bash
# Cross-platform method
npm run cleanup-ports
# Windows PowerShell
powershell -ExecutionPolicy Bypass -File .\scripts\cleanup-ports.ps1
# macOS/Linux
./scripts/cleanup-ports.sh
```
---
## 🤝 Contribution
Welcome to contribute! Please see [Development and Maintenance Manual](./docs/Development and Maintenance Manual.md) to learn how to get started.
---
## 🔧 Technology Stack
- **Browser Extension**: TypeScript + Webpack + Chrome Extension API
- **MCP Server**: Node.js + Express + MCP SDK
- **Port**: 54721-54725 (automatic port discovery)
- **Framework Detection**: React Fiber, Vue 2/3, Angular
### System Requirements
- **Node.js**: >= 16.0.0
- **npm**: >= 7.0.0
- **Browser**: Chrome/Edge 88+ (supports Manifest V3)
- **Operating System**: Windows/macOS/Linux
> **Note**: Although supports Node 16+, recommends using Node 18 LTS or Node 20 LTS for better performance and long-term support.
---
## 📄 License
MIT License - See [LICENSE](LICENSE) file
---
## 🙏 Acknowledgments
Thanks to all contributors and users!
---
**Start using Element Picker and enjoy AI-assisted development!**
