@acertijosapps/electron-viewer 0.0.0-stage → 1.0.0

package/mcp/server.js

@@ -0,0 +1,349 @@
+// MCP del visor: herramientas para que Claude maneje apps Electron.
+// Habla con la API HTTP del visor (server.js) para que cada acción se vea en vivo en el panel;
+// si el visor no está corriendo, usa CDP directo con la misma lógica (lib/electron.js).
+// stdout es del protocolo MCP: los logs van a stderr.
+
+import { readFileSync } from 'node:fs';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { KEY_NAMES, createActions } from '../lib/electron.js';
+
+const VIEWER_URL = (process.env.ELECTRON_VIEWER_URL || 'http://localhost:8094').replace(/\/$/, '');
+const SCREENSHOT_MAX = Number(process.env.SCREENSHOT_MAX) || 1024;
+const VIEWER_TIMEOUT_MS = 60000;
+
+const direct = createActions();
+
+// Error de red (visor apagado) → modo directo. Un error HTTP del visor sí se propaga.
+class ViewerDown extends Error {}
+
+async function viewer(method, route, params = {}) {
+  const url = new URL(VIEWER_URL + route);
+  const init = { method, signal: AbortSignal.timeout(VIEWER_TIMEOUT_MS) };
+  if (method === 'GET') {
+    for (const [k, v] of Object.entries(params)) if (v !== undefined) url.searchParams.set(k, v);
+  } else {
+    init.headers = { 'content-type': 'application/json' };
+    init.body = JSON.stringify(params);
+  }
+  let res;
+  try {
+    res = await fetch(url, init);
+  } catch (err) {
+    if (err.name === 'TimeoutError') throw new Error(`The viewer did not answer within ${VIEWER_TIMEOUT_MS / 1000} s`);
+    throw new ViewerDown(err.message);
+  }
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    throw new Error(body.error || `HTTP ${res.status}`);
+  }
+  const type = res.headers.get('content-type') || '';
+  if (!type.startsWith('image/')) return res.json();
+  const content = res.headers.get('x-content');
+  const vw = res.headers.get('x-viewport-width');
+  return {
+    data: Buffer.from(await res.arrayBuffer()),
+    mimeType: type,
+    width: Number(res.headers.get('x-image-width')),
+    height: Number(res.headers.get('x-image-height')),
+    window: res.headers.get('x-window'),
+    viewport: vw ? { width: Number(vw), height: Number(res.headers.get('x-viewport-height')) } : undefined,
+    content: content ? JSON.parse(content) : undefined,
+  };
+}
+
+// Ejecuta una acción por el visor o, si no está corriendo, por CDP directo.
+async function run(action, method, route, params = {}) {
+  try {
+    return { result: await viewer(method, route, params), via: 'viewer' };
+  } catch (err) {
+    if (!(err instanceof ViewerDown)) throw err;
+    return { result: await direct[action](params), via: 'cdp' };
+  }
+}
+
+const text = (value) => ({ content: [{ type: 'text', text: typeof value === 'string' ? value : JSON.stringify(value, null, 2) }] });
+
+const windowArg = z
+  .string()
+  .optional()
+  .describe('Window: target id from list_windows or part of its title. Optional when only one window is open.');
+const appArg = z.string().optional().describe('App: id (its CDP port) or name from list_windows. Optional with a single app.');
+const coord = (what) => z.number().min(0).max(1).describe(`${what}, normalized 0–1 over the screenshot`);
+const modifiersArg = z.array(z.enum(['alt', 'ctrl', 'meta', 'shift'])).optional().describe('Modifier keys held during the action (meta = ⌘ on macOS)');
+
+const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+const server = new McpServer({ name: 'electron-viewer', version });
+
+server.registerTool(
+  'list_windows',
+  {
+    title: 'List windows',
+    description:
+      'Lists the running Electron apps (found on CDP ports 9222–9231, launched or attached) and their windows. ' +
+      'main=true means the main process is reachable (evaluate_main, frame screenshots, real window resizing). ' +
+      'Includes the viewer URL to watch a window live in a browser pane.',
+    annotations: { readOnlyHint: true },
+  },
+  async () => {
+    const { result: apps, via } = await run('windows', 'GET', '/api/windows');
+    return text({
+      apps,
+      viewer: via === 'viewer' ? VIEWER_URL : 'not running (start it with `npx @acertijosapps/electron-viewer`)',
+    });
+  },
+);
+
+server.registerTool(
+  'launch_app',
+  {
+    title: 'Launch app',
+    description:
+      'Starts the Electron project with `electron .` (its own node_modules/electron) on free debugging ports, ' +
+      'so both the renderer (CDP) and the main process (Node inspector) are reachable. Waits for the first window.',
+    inputSchema: {
+      project: z.string().optional().describe('Project folder (default: the folder the viewer or MCP was started in)'),
+    },
+  },
+  async ({ project }) => text((await run('launch', 'POST', '/api/launch', { project })).result),
+);
+
+server.registerTool(
+  'attach',
+  {
+    title: 'Attach to app',
+    description:
+      'Attaches to an Electron app already running with --remote-debugging-port=<port> (and optionally ' +
+      '--inspect=<inspect_port> for the main process). Apps on ports 9222–9231 are found without attaching.',
+    inputSchema: {
+      port: z.number().int().min(1).max(65535).describe('CDP port (--remote-debugging-port)'),
+      inspect_port: z.number().int().min(1).max(65535).optional().describe('Main process inspector port (--inspect)'),
+    },
+  },
+  async ({ port, inspect_port }) => text((await run('attach', 'POST', '/api/attach', { port, inspectPort: inspect_port })).result),
+);
+
+server.registerTool(
+  'screenshot',
+  {
+    title: 'Screenshot',
+    description:
+      'Captures the window content (PNG). For click, drag, hover and scroll use normalized coordinates: ' +
+      'x = pixel_x / image width, y = pixel_y / image height. With frame=true it captures the screen area of ' +
+      'the window instead, with its native title bar, menus and dialogs (needs main=true; on macOS the app needs ' +
+      'the Screen Recording permission); coordinates still refer to the content screenshot.',
+    inputSchema: {
+      window: windowArg,
+      frame: z.boolean().optional().describe('Include the native window frame, menus and dialogs'),
+    },
+    annotations: { readOnlyHint: true },
+  },
+  async ({ window, frame }) => {
+    const { result: shot } = await run('screenshot', 'GET', '/api/screenshot', { window, max: SCREENSHOT_MAX, frame: frame ? 1 : undefined });
+    const c = shot.content;
+    const note = c
+      ? `Window with frame, ${shot.width}×${shot.height} px. Content area: x ${c.x.toFixed(3)}–${(c.x + c.width).toFixed(3)}, ` +
+        `y ${c.y.toFixed(3)}–${(c.y + c.height).toFixed(3)} of the image; click coordinates are normalized over the content only.`
+      : `Viewport is ${shot.viewport?.width}×${shot.viewport?.height} CSS px (image ${shot.width}×${shot.height}, longest side ≤ ${SCREENSHOT_MAX}).`;
+    return {
+      content: [
+        { type: 'image', data: shot.data.toString('base64'), mimeType: shot.mimeType },
+        { type: 'text', text: `${note} Window ${shot.window}.` },
+      ],
+    };
+  },
+);
+
+server.registerTool(
+  'click',
+  {
+    title: 'Click',
+    description: 'Clicks a point of the window content (Input.dispatchMouseEvent). count=2 is a double click.',
+    inputSchema: {
+      x: coord('x coordinate'),
+      y: coord('y coordinate'),
+      button: z.enum(['left', 'right', 'middle']).default('left').describe('Mouse button'),
+      count: z.number().int().min(1).max(3).default(1).describe('Click count (2 = double click)'),
+      modifiers: modifiersArg,
+      window: windowArg,
+    },
+  },
+  async ({ x, y, button, count, modifiers, window }) => {
+    await run('click', 'POST', '/api/click', { window, x, y, button, count, modifiers });
+    return text(`${count === 2 ? 'double-' : ''}clicked ${button} at (${x.toFixed(3)}, ${y.toFixed(3)})`);
+  },
+);
+
+server.registerTool(
+  'drag',
+  {
+    title: 'Drag',
+    description: 'Presses the left button at one point, moves to another with intermediate steps and releases (a real drag).',
+    inputSchema: {
+      x1: coord('Start x'),
+      y1: coord('Start y'),
+      x2: coord('End x'),
+      y2: coord('End y'),
+      duration_ms: z.number().int().min(0).max(10000).default(300).describe('Drag duration in ms'),
+      modifiers: modifiersArg,
+      window: windowArg,
+    },
+  },
+  async ({ x1, y1, x2, y2, duration_ms, modifiers, window }) => {
+    await run('drag', 'POST', '/api/drag', { window, x1, y1, x2, y2, ms: duration_ms, modifiers });
+    return text(`dragged (${x1.toFixed(3)}, ${y1.toFixed(3)}) → (${x2.toFixed(3)}, ${y2.toFixed(3)}) in ${duration_ms} ms`);
+  },
+);
+
+server.registerTool(
+  'hover',
+  {
+    title: 'Hover',
+    description: 'Moves the mouse to a point without clicking (hover effects, tooltips).',
+    inputSchema: { x: coord('x coordinate'), y: coord('y coordinate'), window: windowArg },
+  },
+  async ({ x, y, window }) => {
+    await run('hover', 'POST', '/api/hover', { window, x, y });
+    return text(`hovering at (${x.toFixed(3)}, ${y.toFixed(3)})`);
+  },
+);
+
+server.registerTool(
+  'scroll',
+  {
+    title: 'Scroll',
+    description: 'Scrolls with the mouse wheel at a point. Positive delta_y scrolls down; deltas are in CSS pixels.',
+    inputSchema: {
+      x: coord('x coordinate').default(0.5),
+      y: coord('y coordinate').default(0.5),
+      delta_x: z.number().default(0).describe('Horizontal delta in CSS px'),
+      delta_y: z.number().default(400).describe('Vertical delta in CSS px'),
+      window: windowArg,
+    },
+  },
+  async ({ x, y, delta_x, delta_y, window }) => {
+    await run('scroll', 'POST', '/api/scroll', { window, x, y, dx: delta_x, dy: delta_y });
+    return text(`scrolled (${delta_x}, ${delta_y}) at (${x.toFixed(3)}, ${y.toFixed(3)})`);
+  },
+);
+
+server.registerTool(
+  'type_text',
+  {
+    title: 'Type text',
+    description: 'Types text into the focused element (Input.insertText; any Unicode). Click the field first; for Enter or shortcuts use press_key.',
+    inputSchema: { text: z.string().min(1).max(10000).describe('Text to type'), window: windowArg },
+  },
+  async ({ text: value, window }) => {
+    await run('text', 'POST', '/api/text', { window, text: value });
+    return text(`typed ${JSON.stringify(value)}`);
+  },
+);
+
+server.registerTool(
+  'press_key',
+  {
+    title: 'Press key',
+    description:
+      `Presses a key, optionally with modifiers (e.g. key "a" + ["meta"] selects all on macOS). Named keys: ${KEY_NAMES.join(', ')}; ` +
+      'or any single character.',
+    inputSchema: { key: z.string().min(1).describe('Key name or single character'), modifiers: modifiersArg, window: windowArg },
+  },
+  async ({ key, modifiers, window }) => {
+    await run('key', 'POST', '/api/key', { window, key, modifiers });
+    return text(`pressed ${[...(modifiers || []), key].join('+')}`);
+  },
+);
+
+server.registerTool(
+  'resize_window',
+  {
+    title: 'Resize window',
+    description:
+      'Sets the size of the window content area in CSS px. With the main process it resizes the real window; ' +
+      'without it, it emulates the viewport. Width and height 0 restore the window size.',
+    inputSchema: {
+      width: z.number().int().min(0).max(8000).describe('Content width in CSS px'),
+      height: z.number().int().min(0).max(8000).describe('Content height in CSS px'),
+      window: windowArg,
+    },
+  },
+  async ({ width, height, window }) => text((await run('resize', 'POST', '/api/resize', { window, width, height })).result),
+);
+
+server.registerTool(
+  'reload',
+  {
+    title: 'Reload',
+    description: 'Reloads the page of the window (renderer only; the main process keeps running).',
+    inputSchema: { ignore_cache: z.boolean().optional().describe('Bypass the cache'), window: windowArg },
+  },
+  async ({ ignore_cache, window }) => {
+    await run('reload', 'POST', '/api/reload', { window, ignoreCache: ignore_cache });
+    return text('reloaded');
+  },
+);
+
+server.registerTool(
+  'evaluate',
+  {
+    title: 'Evaluate in renderer',
+    description:
+      'Evaluates a JavaScript expression in the window page (main world) and returns its JSON value. Promises are awaited.',
+    inputSchema: { expression: z.string().min(1).describe('JavaScript expression'), window: windowArg },
+  },
+  async ({ expression, window }) => text((await run('evaluate', 'POST', '/api/evaluate', { window, expression })).result),
+);
+
+server.registerTool(
+  'evaluate_main',
+  {
+    title: 'Evaluate in main process',
+    description:
+      "Evaluates a JavaScript expression in the app's main process (Node inspector) and returns its JSON value. " +
+      "`require` is available, e.g. require('electron').BrowserWindow.getAllWindows().map(w => w.getTitle()). " +
+      'Promises are awaited. Needs main=true in list_windows.',
+    inputSchema: { expression: z.string().min(1).describe('JavaScript expression'), app: appArg },
+  },
+  async ({ expression, app }) => text((await run('evaluateMain', 'POST', '/api/evaluate-main', { app, expression })).result),
+);
+
+server.registerTool(
+  'get_accessibility_tree',
+  {
+    title: 'Accessibility tree',
+    description:
+      'Returns the accessibility tree of the window as indented text (role "name" value [state]). Interactive ' +
+      'elements carry @(x, y): their center, normalized like click coordinates.',
+    inputSchema: {
+      interactive_only: z.boolean().default(false).describe('Only interactive elements, as a flat list'),
+      window: windowArg,
+    },
+    annotations: { readOnlyHint: true },
+  },
+  async ({ interactive_only, window }) =>
+    text((await run('axTree', 'GET', '/api/ax-tree', { window, interactiveOnly: interactive_only })).result.tree),
+);
+
+server.registerTool(
+  'get_console_logs',
+  {
+    title: 'Console logs',
+    description:
+      'Console messages and uncaught exceptions of the app: renderer windows and main process (up to the last 1000). ' +
+      'source "stdout" returns the raw output of an app started with launch_app.',
+    inputSchema: {
+      level: z.string().optional().describe('Comma-separated levels to keep: log, info, warn, error, debug'),
+      source: z.enum(['all', 'renderer', 'main', 'stdout']).default('all').describe('Where the messages come from'),
+      limit: z.number().int().min(1).max(1000).default(100).describe('Most recent entries to return'),
+      window: windowArg.describe('Only this window (plus the main process)'),
+      app: appArg,
+    },
+    annotations: { readOnlyHint: true },
+  },
+  async ({ level, source, limit, window, app }) => text((await run('logs', 'GET', '/api/logs', { level, source, limit, window, app })).result),
+);
+
+await server.connect(new StdioServerTransport());
+console.error(`electron-viewer MCP ready (viewer: ${VIEWER_URL})`);

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@acertijosapps/electron-viewer",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "mcpName": "io.github.acertijosapps/electron-viewer",
+  "version": "1.0.0",
+  "description": "Visor web de apps Electron en vivo (screencast por CDP, input de mouse y teclado, captura con el marco nativo) y MCP para que un agente las maneje.",
+  "type": "module",
+  "main": "server.js",
+  "bin": {
+    "electron-viewer": "bin/electron-viewer.js"
+  },
+  "files": [
+    "bin",
+    "server.js",
+    "lib",
+    "mcp",
+    "public",
+    "media",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node bin/electron-viewer.js",
+    "mcp": "node bin/electron-viewer.js mcp",
+    "example": "node bin/electron-viewer.js --project example",
+    "check": "node --check bin/electron-viewer.js && node --check server.js && node --check lib/cdp.js && node --check lib/electron.js && node --check mcp/server.js && node --check public/viewer.js",
+    "prepare": "git config core.hooksPath .githooks || exit 0"
+  },
+  "keywords": [
+    "electron",
+    "cdp",
+    "chrome-devtools-protocol",
+    "screencast",
+    "viewer",
+    "automation",
+    "mcp",
+    "model-context-protocol",
+    "claude-code"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/acertijosapps/electron-viewer.git"
+  },
+  "author": "AcertijosApps <acertijos.contacto@gmail.com> (https://acertijosapps.com/librerias/)",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/acertijosapps/electron-viewer/issues"
+  },
+  "homepage": "https://acertijosapps.com/librerias/",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "ws": "^8.18.0",
+    "zod": "4.6.7"
+  }
+}

package/public/index.html

@@ -0,0 +1,58 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Electron Viewer</title>
+    <link rel="stylesheet" href="style.css" />
+  </head>
+  <body>
+    <header class="bar">
+      <select id="window" aria-label="Window"></select>
+      <button id="launch-top" class="primary" hidden>Launch</button>
+      <span id="status" aria-live="polite"></span>
+    </header>
+    <main id="stage">
+      <canvas id="screen" width="0" height="0" aria-label="App window"></canvas>
+      <textarea id="keys" aria-label="Keyboard input for the app" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"></textarea>
+      <div id="placeholder">
+        <p id="placeholder-text">Connecting…</p>
+        <button id="launch" class="primary" hidden>Launch app</button>
+        <form id="attach" hidden>
+          <label for="attach-port">or attach to a debugging port</label>
+          <input id="attach-port" type="number" min="1" max="65535" value="9222" aria-label="CDP port" />
+          <button type="submit">Attach</button>
+        </form>
+      </div>
+    </main>
+    <footer class="bar controls">
+      <div class="group" role="group" aria-label="Page">
+        <button id="reload" title="Reload">
+          <svg viewBox="0 0 24 24" aria-hidden="true"><path d="M20 5v5h-5" /><path d="M18.5 15a7 7 0 1 1-1.2-7.4L20 10" /></svg>
+        </button>
+        <button id="devtools" title="Toggle DevTools">
+          <svg viewBox="0 0 24 24" aria-hidden="true"><path d="m9 8-4 4 4 4M15 8l4 4-4 4" /></svg>
+        </button>
+      </div>
+      <div class="group" role="group" aria-label="Window size">
+        <select id="size" title="Window size">
+          <option value="">Window size</option>
+          <option value="1440x900">1440 × 900</option>
+          <option value="1280x800">1280 × 800</option>
+          <option value="1024x768">1024 × 768</option>
+          <option value="800x600">800 × 600</option>
+          <option value="390x844">390 × 844</option>
+        </select>
+      </div>
+      <div class="group" role="group" aria-label="Capture">
+        <button id="frame" title="Show the native window frame, menus and dialogs (needs the main process)" aria-pressed="false">
+          <svg viewBox="0 0 24 24" aria-hidden="true"><rect x="3.5" y="4.5" width="17" height="15" rx="2" /><path d="M3.5 9h17" /></svg>
+        </button>
+        <button id="screenshot" title="Save screenshot (PNG)">
+          <svg viewBox="0 0 24 24" aria-hidden="true"><path d="M4 8h3l2-2.5h6L17 8h3v11H4z" /><circle cx="12" cy="13" r="3.5" /></svg>
+        </button>
+      </div>
+    </footer>
+    <script type="module" src="viewer.js"></script>
+  </body>
+</html>