Implement multi-instance WebSocket server with leader election

- Add port-based leader election for WebSocket server instances
- Create SharedStateService for filesystem-based state persistence
- Refactor services with proper separation of concerns
- Add comprehensive test suite using Node.js built-in test runner
- Rename WebSocketMessageType to PointerMessageType for clarity
- Configure changesets with linked packages for version alignment
- Bump all packages to version 0.3.0

Author: elieteyssedou

packages/server/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @mcp-pointer/server
 
+## 0.3.0
+
+### Minor 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
+
+### Patch Changes
+
+- Updated dependencies
+  - @mcp-pointer/shared@0.3.0
+
 ## 0.2.0
 
 ### Minor Changes

packages/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-pointer/server",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "MCP Server for DOM element pointing - WebSocket bridge for element targeting",
   "type": "module",
   "main": "dist/index.js",
@@ -14,7 +14,8 @@
     "typecheck": "tsc --noEmit",
     "configure": "tsx src/cli.ts configure",
     "link:global": "pnpm build && pnpm link --global",
-    "build:start": "node dist/cli.cjs start"
+    "build:start": "node dist/cli.cjs start",
+    "test": "tsx --test src/__tests__/**/*.test.ts"
   },
   "dependencies": {
     "@mcp-pointer/shared": "workspace:*",

packages/server/src/__tests__/services/shared-state-service.test.ts

@@ -0,0 +1,92 @@
+import {
+  describe, it, before, after,
+} from 'node:test';
+import assert from 'node:assert';
+import fs from 'fs/promises';
+import SharedStateService from '../../services/shared-state-service';
+import {
+  setupTestDir, cleanupTestFiles, createMockElement, TEST_SHARED_STATE_PATH,
+} from '../test-helpers';
+
+// Override the shared state path for testing
+
+describe('SharedStateService', () => {
+  let service: SharedStateService;
+
+  before(async () => {
+    await setupTestDir();
+
+    // Monkey-patch the constant for testing
+    const SharedStateServiceModule = await import('../../services/shared-state-service');
+    (SharedStateServiceModule.default as any).prototype.constructor = function testConstructor() {
+      // Use test path instead of default
+      this.filePath = TEST_SHARED_STATE_PATH;
+    };
+
+    service = new SharedStateService();
+  });
+
+  after(async () => {
+    await cleanupTestFiles();
+  });
+
+  it('should save and load current element', async () => {
+    const mockElement = createMockElement();
+
+    await service.saveCurrentElement(mockElement);
+    const loaded = await service.getCurrentElement();
+
+    assert.deepStrictEqual(loaded, mockElement);
+  });
+
+  it('should handle null element', async () => {
+    await service.saveCurrentElement(null);
+    const loaded = await service.getCurrentElement();
+
+    assert.strictEqual(loaded, null);
+  });
+
+  it('should return null for missing file', async () => {
+    await cleanupTestFiles();
+    await setupTestDir();
+
+    const loaded = await service.getCurrentElement();
+
+    assert.strictEqual(loaded, null);
+  });
+
+  it('should handle corrupted file gracefully', async () => {
+    // Write corrupted data to the file
+    await fs.writeFile(TEST_SHARED_STATE_PATH, 'not json at all', 'utf8');
+
+    const loaded = await service.getCurrentElement();
+
+    assert.strictEqual(loaded, null);
+  });
+
+  it('should save element over corrupted file', async () => {
+    // First create a corrupted file
+    await fs.writeFile(TEST_SHARED_STATE_PATH, 'corrupted content', 'utf8');
+
+    // Save a new element over it
+    const mockElement = createMockElement();
+    await service.saveCurrentElement(mockElement);
+
+    // Should be able to load the new element
+    const loaded = await service.getCurrentElement();
+
+    assert.deepStrictEqual(loaded, mockElement);
+  });
+
+  it('should overwrite previous element', async () => {
+    const firstElement = createMockElement();
+    const secondElement = { ...createMockElement(), id: 'second-element' };
+
+    await service.saveCurrentElement(firstElement);
+    await service.saveCurrentElement(secondElement);
+
+    const loaded = await service.getCurrentElement();
+
+    assert.deepStrictEqual(loaded, secondElement);
+  });
+});

packages/server/src/__tests__/test-helpers.ts

@@ -0,0 +1,55 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { type TargetedElement } from '@mcp-pointer/shared';
+
+// ES module equivalent of __dirname
+// eslint-disable-next-line @typescript-eslint/naming-convention, no-underscore-dangle
+const __filename = fileURLToPath(import.meta.url);
+// eslint-disable-next-line @typescript-eslint/naming-convention, no-underscore-dangle
+const __dirname = path.dirname(__filename);
+
+// Test constants
+export const TEST_MCP_POINTER_PORT = 7008;
+export const TEST_TEMP_DIR = path.join(__dirname, 'tmp');
+export const TEST_SHARED_STATE_PATH = path.join(TEST_TEMP_DIR, 'mcp-pointer-test-shared-state.json');
+
+export async function setupTestDir(): Promise<void> {
+  try {
+    await fs.mkdir(TEST_TEMP_DIR, { recursive: true });
+  } catch {
+    // Directory exists, ignore
+  }
+}
+
+export async function cleanupTestFiles(): Promise<void> {
+  try {
+    await fs.rm(TEST_TEMP_DIR, { recursive: true, force: true });
+  } catch {
+    // Directory doesn't exist, ignore
+  }
+}
+
+export function createMockElement(): TargetedElement {
+  return {
+    selector: 'div.test-element',
+    tagName: 'DIV',
+    id: 'test-id',
+    classes: ['test-class'],
+    innerText: 'Test Element',
+    attributes: { 'data-test': 'true' },
+    position: {
+      x: 100, y: 200, width: 300, height: 50,
+    },
+    cssProperties: {
+      display: 'block',
+      position: 'relative',
+      fontSize: '16px',
+      color: 'rgb(0, 0, 0)',
+      backgroundColor: 'rgb(255, 255, 255)',
+    },
+    timestamp: Date.now(),
+    url: 'https://example.com',
+    tabId: 123,
+  };
+}

packages/server/src/services/mcp-service.ts

@@ -0,0 +1,98 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { version } from 'process';
+import SharedStateService from './shared-state-service';
+
+enum MCPToolName {
+  GET_POINTED_ELEMENT = 'get-pointed-element',
+}
+
+enum MCPServerName {
+  MCP_POINTER = 'mcp-pointer',
+}
+
+export default class MCPService {
+  private server: Server;
+
+  private sharedState: SharedStateService;
+
+  constructor(sharedState: SharedStateService) {
+    this.sharedState = sharedState;
+    this.server = new Server(
+      {
+        name: MCPServerName.MCP_POINTER,
+        version,
+      },
+      {
+        capabilities: {
+          tools: {},
+        },
+      },
+    );
+
+    this.setupHandlers();
+  }
+
+  private setupHandlers(): void {
+    this.server.setRequestHandler(ListToolsRequestSchema, this.handleListTools.bind(this));
+    this.server.setRequestHandler(CallToolRequestSchema, this.handleCallTool.bind(this));
+  }
+
+  private async handleListTools() {
+    return {
+      tools: [
+        {
+          name: MCPToolName.GET_POINTED_ELEMENT,
+          description: 'Get information about the currently pointed/shown DOM element from the browser extension, in order to let you see a specific element the user is showing you on his/her the browser.',
+          inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+          },
+        },
+      ],
+    };
+  }
+
+  private async handleCallTool(request: any) {
+    if (request.params.name === MCPToolName.GET_POINTED_ELEMENT) {
+      return this.getTargetedElement();
+    }
+
+    throw new Error(`Unknown tool: ${request.params.name}`);
+  }
+
+  private async getTargetedElement() {
+    const element = await this.sharedState.getCurrentElement();
+
+    if (!element) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: 'No element is currently pointed. '
+              + 'The user needs to point an element in their browser using Option+Click.',
+          },
+        ],
+      };
+    }
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(element, null, 2),
+        },
+      ],
+    };
+  }
+
+  public async start(): Promise<void> {
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+  }
+}

packages/server/src/services/shared-state-service.ts

@@ -0,0 +1,32 @@
+import fs from 'fs/promises';
+import { type TargetedElement } from '@mcp-pointer/shared';
+import logger from '../logger';
+
+// Shared state constants
+const SHARED_STATE_FILE_PATH = '/tmp/mcp-pointer-shared-state.json';
+
+export default class SharedStateService {
+  public async saveCurrentElement(element: TargetedElement | null): Promise<void> {
+    try {
+      const json = JSON.stringify(element, null, 2);
+      await fs.writeFile(SHARED_STATE_FILE_PATH, json, 'utf8');
+      logger.debug('Current element saved to shared state file');
+    } catch (error) {
+      logger.error('Failed to save current element:', error);
+    }
+  }
+
+  public async getCurrentElement(): Promise<TargetedElement | null> {
+    try {
+      const json = await fs.readFile(SHARED_STATE_FILE_PATH, 'utf8');
+      return JSON.parse(json);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+        logger.debug('Shared state file does not exist');
+        return null;
+      }
+      logger.error('Failed to load current element:', error);
+      return null;
+    }
+  }
+}