html2pptx-local-mcp 1.1.19 → 1.1.21

package/lib/local-editor-server.js

@@ -0,0 +1,316 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import net from 'node:net';
+import { access } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  readEditorServerState,
+  writeEditorServerState,
+} from './local-editor-state.js';
+
+const AUTO_PORT = 0;
+const DEFAULT_READY_TIMEOUT_MS = 30000;
+
+export function createLocalEditorServerManager(options = {}) {
+  const sessions = new Map();
+  const launchTimeoutMs = Number.isFinite(options.launchTimeoutMs)
+    ? Math.max(1000, Math.floor(options.launchTimeoutMs))
+    : DEFAULT_READY_TIMEOUT_MS;
+
+  async function ensure(root = process.cwd(), input = {}) {
+    const projectRoot = resolve(root);
+    const requestedPort = normalizePort(input.editorPort ?? process.env.HTML2PPTX_STUDIO_PORT ?? process.env.PORT, AUTO_PORT);
+
+    const registered = await readEditorServerState(projectRoot);
+    if (registered && await isEditorServer(registered.port)) {
+      return {
+        baseUrl: registered.baseUrl,
+        port: registered.port,
+        reused: true,
+      };
+    }
+
+    const existing = sessions.get(projectRoot);
+    if (existing && !existing.child.killed && existing.child.exitCode == null && await isEditorServer(existing.port)) {
+      await writeEditorServerState(projectRoot, {
+        baseUrl: existing.baseUrl,
+        port: existing.port,
+        pid: existing.child.pid,
+      });
+      return {
+        baseUrl: existing.baseUrl,
+        port: existing.port,
+        reused: true,
+      };
+    }
+
+    if (requestedPort !== AUTO_PORT && await isEditorServer(requestedPort)) {
+      const baseUrl = `http://localhost:${requestedPort}`;
+      await writeEditorServerState(projectRoot, {
+        baseUrl,
+        port: requestedPort,
+        pid: null,
+      });
+      return {
+        baseUrl,
+        port: requestedPort,
+        reused: true,
+      };
+    }
+
+    const appRoot = await resolveEditorAppRoot(options);
+    const port = requestedPort === AUTO_PORT ? await getEphemeralPort() : await pickOpenPort(requestedPort);
+    const baseUrl = `http://localhost:${port}`;
+    const invocation = await resolveNextInvocation(appRoot, options);
+
+    const child = spawn(invocation.command, [
+      ...invocation.baseArgs,
+      'dev',
+      '--webpack',
+      '-p',
+      String(port),
+    ], {
+      cwd: appRoot,
+      env: {
+        ...process.env,
+        HTML2PPTX_EDITOR_BASE_URL: baseUrl,
+        NEXT_TELEMETRY_DISABLED: '1',
+        PORT: String(port),
+      },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    const session = {
+      child,
+      appRoot,
+      baseUrl,
+      port,
+      stdout: '',
+      stderr: '',
+      startedAt: new Date().toISOString(),
+    };
+    sessions.set(projectRoot, session);
+
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => {
+      session.stdout += chunk;
+    });
+    child.stderr.on('data', (chunk) => {
+      session.stderr += chunk;
+    });
+    child.once('exit', () => {
+      if (sessions.get(projectRoot) === session) sessions.delete(projectRoot);
+    });
+
+    await waitForEditorServer(session, launchTimeoutMs);
+    await writeEditorServerState(projectRoot, {
+      baseUrl,
+      port,
+      pid: child.pid,
+    });
+
+    return {
+      baseUrl,
+      port,
+      pid: child.pid,
+      reused: false,
+    };
+  }
+
+  function stopAll() {
+    for (const session of sessions.values()) {
+      session.child.kill('SIGTERM');
+    }
+    sessions.clear();
+  }
+
+  return {
+    ensure,
+    stopAll,
+  };
+}
+
+export const localEditorServerManager = createLocalEditorServerManager();
+
+export async function ensureLocalEditorServer(root = process.cwd(), options = {}) {
+  return localEditorServerManager.ensure(root, options);
+}
+
+export async function resolveEditorAppRoot(options = {}) {
+  if (options.appRoot) return resolve(options.appRoot);
+  if (process.env.HTML2PPTX_EDITOR_APP_ROOT) return resolve(process.env.HTML2PPTX_EDITOR_APP_ROOT);
+
+  const packageRoot = fileURLToPath(new URL('..', import.meta.url));
+  const packagedAppRoot = join(packageRoot, 'local-editor-app');
+  if (existsSync(join(packagedAppRoot, 'app', 'edit-slide', 'page.jsx'))) {
+    return packagedAppRoot;
+  }
+  if (existsSync(join(packageRoot, 'app', 'edit-slide', 'page.jsx'))) {
+    return packageRoot;
+  }
+
+  throw new Error(
+    'html2pptx local editor app is not bundled. Reinstall html2pptx-local-mcp or pass HTML2PPTX_EDITOR_APP_ROOT.',
+  );
+}
+
+export async function resolveNextInvocation(appRoot, options = {}) {
+  if (options.command) {
+    return {
+      command: options.command,
+      baseArgs: Array.isArray(options.baseArgs) ? options.baseArgs : [],
+    };
+  }
+  if (process.env.HTML2PPTX_NEXT_BIN) {
+    return {
+      command: process.execPath,
+      baseArgs: [process.env.HTML2PPTX_NEXT_BIN],
+    };
+  }
+
+  const nextBin = await findUp(join('node_modules', 'next', 'dist', 'bin', 'next'), appRoot);
+  if (nextBin) {
+    return {
+      command: process.execPath,
+      baseArgs: [nextBin],
+    };
+  }
+
+  return {
+    command: 'npx',
+    baseArgs: ['--yes', 'next'],
+  };
+}
+
+export async function isEditorServer(port) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 1500);
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}/api/edit-slide/local-health`, {
+      headers: { accept: 'application/json' },
+      signal: controller.signal,
+    });
+    if (!response.ok) return false;
+    const payload = await response.json();
+    return payload?.app === 'html2pptx-local-editor' && payload?.ok === true;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function waitForEditorServer(session, timeoutMs) {
+  return new Promise((resolvePromise, rejectPromise) => {
+    const startedAt = Date.now();
+    const tick = async () => {
+      if (await isEditorServer(session.port)) {
+        resolvePromise();
+        return;
+      }
+      if (session.child.exitCode != null || session.child.killed) {
+        rejectPromise(new Error([
+          `html2pptx editor server exited before it was ready on ${session.baseUrl}.`,
+          session.stderr.trim() || session.stdout.trim(),
+        ].filter(Boolean).join(' ')));
+        return;
+      }
+      if (Date.now() - startedAt >= timeoutMs) {
+        session.child.kill('SIGTERM');
+        rejectPromise(new Error([
+          `Timed out after ${timeoutMs}ms while starting html2pptx editor server on ${session.baseUrl}.`,
+          session.stderr.trim(),
+        ].filter(Boolean).join(' ')));
+        return;
+      }
+      setTimeout(tick, 350);
+    };
+    tick();
+  });
+}
+
+async function findUp(relativePath, startDir) {
+  let dir = resolve(startDir);
+  while (true) {
+    const candidate = join(dir, relativePath);
+    if (await exists(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function pickOpenPort(preferredPort) {
+  if (!(await isPortOpen(preferredPort))) return preferredPort;
+
+  for (let port = preferredPort + 1; port < preferredPort + 100; port += 1) {
+    if (!(await isPortOpen(port))) return port;
+  }
+  return getEphemeralPort();
+}
+
+function getEphemeralPort() {
+  return new Promise((resolvePromise, rejectPromise) => {
+    const server = net.createServer();
+    server.once('error', rejectPromise);
+    server.listen(0, '127.0.0.1', () => {
+      const address = server.address();
+      server.close(() => {
+        if (!address || typeof address === 'string') {
+          rejectPromise(new Error('Failed to allocate an editor port.'));
+          return;
+        }
+        resolvePromise(address.port);
+      });
+    });
+  });
+}
+
+function isPortOpen(port) {
+  return new Promise((resolvePromise) => {
+    const socket = net.createConnection({ host: '127.0.0.1', port });
+    socket.once('connect', () => {
+      socket.end();
+      resolvePromise(true);
+    });
+    socket.once('error', () => {
+      socket.destroy();
+      resolvePromise(false);
+    });
+  });
+}
+
+function normalizePort(value, fallback) {
+  if (value == null || value === '') return fallback;
+  const port = Number.parseInt(String(value), 10);
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    throw new Error('editorPort must be an integer from 0 to 65535.');
+  }
+  return port;
+}
+
+function installExitHandlers() {
+  const stop = () => localEditorServerManager.stopAll();
+  process.once('exit', stop);
+  process.once('SIGINT', () => {
+    stop();
+    process.exit(130);
+  });
+  process.once('SIGTERM', () => {
+    stop();
+    process.exit(143);
+  });
+}
+
+installExitHandlers();

package/lib/local-editor-state.js

@@ -0,0 +1,45 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+export const EDITOR_SERVER_STATE_FILE = '.html2pptx/edit-slide/editor-server.json';
+export const LEGACY_EDITOR_SERVER_STATE_FILE = '.open-slide/editor-server.json';
+
+export async function readEditorServerState(root = process.cwd()) {
+  for (const stateFile of [EDITOR_SERVER_STATE_FILE, LEGACY_EDITOR_SERVER_STATE_FILE]) {
+    try {
+      const raw = await readFile(join(root, stateFile), 'utf8');
+      const state = JSON.parse(raw);
+      const port = Number.parseInt(state?.port, 10);
+      const baseUrl = typeof state?.baseUrl === 'string' ? state.baseUrl : '';
+      if (!Number.isInteger(port) || port <= 0 || !baseUrl.startsWith('http://')) continue;
+      return {
+        ...state,
+        port,
+        baseUrl,
+      };
+    } catch {
+      // Try the next known state location.
+    }
+  }
+  return null;
+}
+
+export async function readRegisteredEditorBaseUrl(root = process.cwd()) {
+  const state = await readEditorServerState(root);
+  return state?.baseUrl || null;
+}
+
+export async function writeEditorServerState(root, { baseUrl, port, pid, managedBy = 'html2pptx-local-mcp' }) {
+  await mkdir(join(root, '.html2pptx', 'edit-slide'), { recursive: true });
+  await writeFile(
+    join(root, EDITOR_SERVER_STATE_FILE),
+    `${JSON.stringify({
+      baseUrl,
+      port,
+      pid,
+      managedBy,
+      updatedAt: new Date().toISOString(),
+    }, null, 2)}\n`,
+    'utf8',
+  );
+}

package/lib/local-slide-editor-launcher.js

@@ -1,13 +1,12 @@
 import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { existsSync } from 'node:fs';
-import { access, readFile, realpath, stat } from 'node:fs/promises';
-import { dirname, extname, join, relative, resolve, sep } from 'node:path';
+import { access, realpath, stat } from 'node:fs/promises';
+import { dirname, extname, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { ensureLocalEditorServer } from './local-editor-server.js';
 
 const ALLOWED_EXTENSIONS = new Set(['.html', '.htm']);
-const EDITOR_SERVER_STATE_FILE = '.html2pptx/edit-slide/editor-server.json';
-const LEGACY_EDITOR_SERVER_STATE_FILE = '.open-slide/editor-server.json';
 const DEFAULT_LAUNCH_TIMEOUT_MS = 10000;
 
 export function createLocalSlideEditorManager(options = {}) {
@@ -33,7 +32,12 @@ export function createLocalSlideEditorManager(options = {}) {
     }
 
     const baseUrl = normalizeEditorBaseUrl(
-      input.baseUrl || process.env.HTML2PPTX_EDITOR_BASE_URL || await readRegisteredEditorBaseUrl(file.root),
+      input.baseUrl ||
+        process.env.HTML2PPTX_EDITOR_BASE_URL ||
+        await resolveEditorBaseUrl(file.root, {
+          ...input,
+          ensureEditorServer: options.ensureEditorServer,
+        }),
     );
     const port = normalizePort(input.port, 0);
     const openBrowser = input.openBrowser === true;
@@ -148,6 +152,14 @@ export function createLocalSlideEditorManager(options = {}) {
 
 export const localSlideEditorManager = createLocalSlideEditorManager();
 
+async function resolveEditorBaseUrl(root, input = {}) {
+  const ensureEditorServer = typeof input.ensureEditorServer === 'function'
+    ? input.ensureEditorServer
+    : ensureLocalEditorServer;
+  const ensured = await ensureEditorServer(root, input);
+  return ensured.baseUrl;
+}
+
 export async function resolveEditableFile(filePath, cwd = process.cwd()) {
   if (typeof filePath !== 'string' || filePath.trim() === '') {
     throw new Error('filePath must be a non-empty .html or .htm path.');
@@ -305,7 +317,7 @@ export function normalizeEditorBaseUrl(raw) {
   try {
     if (!raw) {
       throw new Error(
-        'Local editor UI is not registered. Start it with `node scripts/dev-studio.mjs`, then retry, or pass baseUrl as a loopback editor URL.',
+        'Local editor UI is not available. Reinstall html2pptx-local-mcp or pass baseUrl as a loopback editor URL.',
       );
     }
     const url = new URL(raw);
@@ -330,18 +342,7 @@ function isAllowedEditorBaseUrl(url) {
   return isLoopbackHostname(url.hostname);
 }
 
-export async function readRegisteredEditorBaseUrl(root = process.cwd()) {
-  for (const stateFile of [EDITOR_SERVER_STATE_FILE, LEGACY_EDITOR_SERVER_STATE_FILE]) {
-    try {
-      const raw = await readFile(join(root, stateFile), 'utf8');
-      const state = JSON.parse(raw);
-      if (typeof state?.baseUrl === 'string') return state.baseUrl;
-    } catch {
-      // Try the next known state location.
-    }
-  }
-  return null;
-}
+export { readRegisteredEditorBaseUrl } from './local-editor-state.js';
 
 function isLoopbackHostname(hostname) {
   const host = String(hostname || '').replace(/^\[|\]$/g, '').toLowerCase();

package/lib/pptx-studio-mcp-core.js

@@ -416,7 +416,7 @@ export const LOCAL_TOOL_DEFINITIONS = [
     name: 'html2pptx_open_local_slide_editor',
     title: 'Open Local Slide Editor',
     description:
-      'Local stdio MCP only. Start the html2pptx CLI local edit bridge for a .html/.htm slide file inside the MCP server working directory, then return the tokenized editor URL. This does not publish or upload the HTML file.',
+      'Local stdio MCP only. Ensure the loopback html2pptx editor UI is running, start the local file bridge for a .html/.htm slide file inside the MCP server working directory, then return the tokenized editor URL. This does not publish or upload the HTML file.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -427,7 +427,13 @@ export const LOCAL_TOOL_DEFINITIONS = [
         },
         baseUrl: {
           type: 'string',
-          description: 'Optional editor base URL. Must be a loopback http(s) origin such as http://localhost:<port>. When omitted, the launcher uses the local editor URL registered by node scripts/dev-studio.mjs. Hosted editor URLs are not allowed for local file editing.',
+          description: 'Optional editor base URL. Must be a loopback http(s) origin such as http://localhost:<port>. When omitted, the local MCP reuses or starts its bundled local editor UI. Hosted editor URLs are not allowed for local file editing.',
+        },
+        editorPort: {
+          type: 'integer',
+          minimum: 0,
+          maximum: 65535,
+          description: 'Optional editor UI port. Defaults to 0 so the OS picks an available loopback port when the local MCP starts the editor UI.',
         },
         port: {
           type: 'integer',
@@ -597,9 +603,9 @@ function buildPromptMessages(name, args) {
               '1. Read html2pptx_get_docs with section="html-contract" to confirm the slide HTML contract.',
               '2. Generate slide-safe HTML. Each slide must be a <section class="slide"> element with explicit dimensions; 1600x900 is the default example unless the request needs a different size.',
               `3. Save the complete HTML document to a project-local .html file, preferably "${fileName}" or another clear path under html2pptx/.`,
-              '4. Open only a loopback editor UI. First ensure the local editor app is running with node scripts/dev-studio.mjs; it will choose an available port and register the editor URL under .html2pptx/edit-slide/editor-server.json in the current project.',
-              '5. Call html2pptx_open_local_slide_editor with { filePath: <path> }. Pass baseUrl only when the user supplied a specific loopback editor URL. Do not use https://html2pptx.app/edit-slide for local file editing.',
-              '6. If that local editor tool is not available, do not pretend the editor was opened. Return the saved HTML path and the local-UI CLI fallback command: npx --yes https://html2pptx.app/downloads/html2pptx-cli-0.4.0.tgz edit <path>. If the CLI reports that the editor is not registered, start node scripts/dev-studio.mjs first.',
+              '4. Call html2pptx_open_local_slide_editor with { filePath: <path> }. The local MCP will reuse or start the loopback editor UI and the localhost file bridge. Pass baseUrl only when the user supplied a specific loopback editor URL. Do not use https://html2pptx.app/edit-slide for local file editing.',
+              '5. If that local editor tool is not available, do not pretend the editor was opened. Return the saved HTML path and the local-UI CLI fallback command: npx --yes https://html2pptx.app/downloads/html2pptx-cli-0.4.0.tgz edit <path>.',
+              '6. If the CLI fallback reports that the editor is not available, use the local MCP package or run the command from an html2pptx source checkout.',
               '7. Do not export PPTX from this prompt. In the editor, the export button should only show a prompt telling the user to ask Claude Code or another agent to use the html2pptx skills for PowerPoint export.',
             ].join('\n'),
           },
@@ -679,7 +685,7 @@ function buildServerInstructions(client = {}, { localOnly = false } = {}) {
       'Use this stdio server only for local visual editing. Use the remote html2pptx MCP server for PPTX export, docs, usage, templates, and publishing workflows.',
       'When the user asks to open, preview, no-code edit, visually edit, or launch an editing screen for generated slides, save the deck as a local .html/.htm file first, usually under html2pptx/<name>.html.',
       'Then call html2pptx_open_local_slide_editor with the project-relative file path.',
-      'The tool starts the html2pptx CLI localhost bridge and does not publish or upload the HTML file.',
+      'The tool starts or reuses the loopback editor UI, starts the html2pptx localhost file bridge, and does not publish or upload the HTML file.',
     ].join('\n');
   }
 
@@ -715,9 +721,8 @@ function buildServerInstructions(client = {}, { localOnly = false } = {}) {
       '',
       'Local visual editing is available in this stdio MCP server.',
       'When the user asks to "open", "preview", "no-code edit", "visually edit", or "launch an editing screen" for generated slides, save the deck as a local .html/.htm file first, usually under html2pptx/<name>.html.',
-      'Use only loopback editor UI for local files. Start node scripts/dev-studio.mjs first; it chooses an available local port and registers the editor URL under .html2pptx/edit-slide/ in the current project. Then call html2pptx_open_local_slide_editor with the project-relative file path. Hosted https://html2pptx.app/edit-slide is not allowed for local file editing.',
-      'If the local editor app is not running, ask the user to start it with node scripts/dev-studio.mjs rather than falling back to a hosted editor URL.',
-      'The tool starts the existing html2pptx CLI localhost bridge and does not publish or upload the HTML file.',
+      'Use only loopback editor UI for local files. Call html2pptx_open_local_slide_editor with the project-relative file path; the local MCP will reuse or start the local editor UI and localhost bridge. Hosted https://html2pptx.app/edit-slide is not allowed for local file editing.',
+      'The tool does not publish or upload the HTML file.',
     );
   } else {
     lines.push(
@@ -911,6 +916,7 @@ export async function executeTool(name, args, client, { sendNotification, progre
       const data = await client.openLocalSlideEditor({
         filePath: args.filePath,
         baseUrl: typeof args.baseUrl === 'string' ? args.baseUrl : undefined,
+        editorPort: Number.isFinite(args.editorPort) ? args.editorPort : undefined,
         port: Number.isFinite(args.port) ? args.port : undefined,
         openBrowser: args.openBrowser === true,
         reuseExisting: args.reuseExisting !== false,

package/local-editor-app/app/api/edit-slide/local-health/route.js

@@ -0,0 +1,16 @@
+import { NextResponse } from 'next/server';
+import { isLoopbackRequest } from '../../../../lib/edit-slide-url-security.js';
+
+export const dynamic = 'force-dynamic';
+
+export function GET(request) {
+  if (!isLoopbackRequest(request.headers)) {
+    return NextResponse.json({ ok: false }, { status: 404 });
+  }
+
+  return NextResponse.json({
+    ok: true,
+    app: 'html2pptx-local-editor',
+    version: 1,
+  });
+}