Complete multi-instance implementation with configuration updates

- Update changeset config with linked packages for version alignment
- Add test command to CI workflow
- Update shared types and package configurations
- Clean up linting and project setup files

Author: elieteyssedou

.changeset/config.json

@@ -3,7 +3,9 @@
   "changelog": "@changesets/cli/changelog",
   "commit": false,
   "fixed": [],
-  "linked": [],
+  "linked": [
+    ["@mcp-pointer/server", "@mcp-pointer/shared", "@mcp-pointer/chrome-extension"]
+  ],
   "access": "restricted",
   "baseBranch": "main",
   "updateInternalDependencies": "patch",

.eslintrc.js

@@ -19,6 +19,7 @@ module.exports = {
   },
   rules: {
     'class-methods-use-this': 'off',
+    'no-await-in-loop': 'off',
   },
   overrides: [
     {

.github/workflows/ci.yml

@@ -32,6 +32,9 @@ jobs:
       - name: Type check
         run: pnpm typecheck
 
+      - name: Run Tests
+        run: pnpm test
+
       - name: Build
         run: pnpm build
 

.gitignore

@@ -4,4 +4,7 @@ dist/
 .DS_Store
 
 # TypeScript
-*.tsbuildinfo
+*.tsbuildinfo
+
+# Test files
+packages/server/src/__tests__/tmp/

CONTRIBUTING.md

@@ -142,6 +142,101 @@ packages/
     └── package.json
 ```
 
+## 🏗️ System Architecture
+
+MCP Pointer uses a distributed architecture with multiple server instances and leader election for high availability:
+
+```mermaid
+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)
+
+1. **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)
+
+2. **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
+
+3. **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)
+
+1. **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
+
+2. **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)
+
+3. **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

package.json

@@ -1,6 +1,5 @@
 {
   "name": "mcp-pointer-monorepo",
-  "version": "0.2.0",
   "description": "👆 MCP Pointer - Point at DOM elements for AI analysis",
   "private": true,
   "packageManager": "pnpm@10.15.0",
@@ -9,6 +8,7 @@
     "build": "pnpm -r run build",
     "lint": "eslint . --ext .ts,.tsx",
     "lint:fix": "eslint . --ext .ts,.tsx --fix",
+    "test": "cd packages/server && pnpm test",
     "typecheck": "tsc --noEmit",
     "changeset": "changeset",
     "version": "changeset version"

packages/chrome-extension/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @mcp-pointer/chrome-extension
 
+## 0.3.0
+
+### Patch Changes
+
+- feat(server): Add multi-instance support with port-based leader election
+
+  - Implement port-based leader election for WebSocket server management
+  - Add shared state persistence to filesystem (/tmp/mcp-pointer-shared-state.json)
+  - Support multiple MCP server instances without port conflicts
+  - Add automatic failover when leader instance crashes (~5 second recovery)
+  - Refactor services into dedicated service layer (WebSocketService, MCPService, SharedStateService)
+  - Add comprehensive test suite using Node.js built-in test runner
+  - Add architecture documentation with Mermaid diagram to CONTRIBUTING.md
+  - Rename WebSocketMessageType to PointerMessageType for better domain clarity
+  - Add proper process cleanup handling on Ctrl+C and other signals
+  - MCP service now runs independently on all instances (leader and followers)
+
+  Breaking changes: None - fully backwards compatible with single instance deployments
+
+- Updated dependencies
+  - @mcp-pointer/shared@0.3.0
+
 ## 0.2.0
 
 ### Minor Changes

packages/chrome-extension/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-pointer/chrome-extension",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": true,
   "scripts": {
     "clean": "rm -rf dist",

packages/chrome-extension/src/background.ts

@@ -1,4 +1,4 @@
-import { ConnectionStatus } from '@mcp-pointer/shared';
+import { ConnectionStatus } from '@mcp-pointer/shared/types';
 import logger from './logger';
 import { ElementSenderService } from './services/element-sender-service';
 import { ConfigStorage } from './storage';

packages/chrome-extension/src/services/element-sender-service.ts

@@ -1,7 +1,7 @@
 import ReconnectingWebSocket from 'reconnecting-websocket';
 import {
-  TargetedElement, WebSocketMessage, WebSocketMessageType, ConnectionStatus,
-} from '@mcp-pointer/shared';
+  TargetedElement, PointerMessage, PointerMessageType, ConnectionStatus,
+} from '@mcp-pointer/shared/types';
 import logger from '../logger';
 
 export type StatusCallback = (status: ConnectionStatus, error?: string) => void;
@@ -44,8 +44,8 @@ export class ElementSenderService {
       // Now sending the element
       statusCallback?.(ConnectionStatus.SENDING);
 
-      const message: WebSocketMessage = {
-        type: WebSocketMessageType.ELEMENT_SELECTED,
+      const message: PointerMessage = {
+        type: PointerMessageType.ELEMENT_SELECTED,
         data: element,
         timestamp: Date.now(),
       };