html2pptx-local-mcp 1.1.19 → 1.1.20

package/app/docs/content.js

@@ -186,7 +186,7 @@ npx skills add https://html2pptx.app --list
 npx skills add https://html2pptx.app
 
 # Claude Code users: run this one line
-npx -y -p html2pptx-local-mcp@latest html2pptx-install-mcp claude`;
+npx --yes --package html2pptx-local-mcp@latest html2pptx-install-mcp claude`;
 
 const SKILL_INSTALL_COMMAND_JA = `# 使うエージェントのコマンドを選択
 # Claude Code
@@ -208,7 +208,7 @@ npx skills add https://html2pptx.app --list
 npx skills add https://html2pptx.app
 
 # Claude Codeユーザーはこの1行でOK
-npx -y -p html2pptx-local-mcp@latest html2pptx-install-mcp claude`;
+npx --yes --package html2pptx-local-mcp@latest html2pptx-install-mcp claude`;
 
 const SKILL_INVOCATION_EXAMPLE = `# 例: Claude Code でスライド作成 → PPTX出力
 
@@ -244,7 +244,7 @@ const SKILL_AVAILABLE_LIST = [
 ];
 
 const MCP_INSTALL_EXAMPLE = `# Claude Codeユーザーはこの1行でOK
-npx -y -p html2pptx-local-mcp@latest html2pptx-install-mcp claude`;
+npx --yes --package html2pptx-local-mcp@latest html2pptx-install-mcp claude`;
 
 const MCP_CONFIG_EXAMPLE = `// 方法2: 設定ファイルに手動追加
 
@@ -256,7 +256,7 @@ const MCP_CONFIG_EXAMPLE = `// 方法2: 設定ファイルに手動追加
   "mcpServers": {
     "html2pptx": {
       "command": "npx",
-      "args": ["-y", "-p", "html2pptx-local-mcp@latest", "html2pptx-mcp"],
+      "args": ["--yes", "--package", "html2pptx-local-mcp@latest", "html2pptx-mcp"],
       "env": {
         "PPTX_STUDIO_API_KEY": "sk_live_xxxx",
         "PPTX_STUDIO_BASE_URL": "http://127.0.0.1:<app-port>"
@@ -858,9 +858,9 @@ echo 'HTML2PPTX_API_KEY=sk_live_xxxx' >> .env`,
         icon: 'https://cdn.jsdelivr.net/gh/glincker/thesvg@main/public/icons/claude/default.svg',
         recommended: true,
         steps: [
-          { title: 'Claude Code users: run this one line', body: 'This registers remote export as `html2pptx`, then writes local edit-slide as `html2pptx-local` directly into Claude Code user config.', code: `npx -y -p html2pptx-local-mcp@latest html2pptx-install-mcp claude` },
+          { title: 'Claude Code users: run this one line', body: 'This registers remote export as `html2pptx`, then writes local edit-slide as `html2pptx-local` directly into Claude Code user config.', code: `npx --yes --package html2pptx-local-mcp@latest html2pptx-install-mcp claude` },
           { title: 'Manual remote setup', body: 'If you only need hosted export tools, add the remote MCP server directly.', code: `claude mcp add --scope user --transport http html2pptx https://html2pptx.app/mcp` },
-          { title: 'Compatible local edit-slide setup', body: 'If Claude Code stdio registration is unreliable, use the installer because it writes the local server entry directly.', code: `npx -y -p html2pptx-local-mcp@latest html2pptx-install-mcp claude` },
+          { title: 'Compatible local edit-slide setup', body: 'If Claude Code stdio registration is unreliable, use the installer because it writes the local server entry directly.', code: `npx --yes --package html2pptx-local-mcp@latest html2pptx-install-mcp claude` },
         ],
         tip: 'The installer registers the remote MCP with user scope and writes the local stdio MCP directly to Claude Code user config for better compatibility.',
       },
@@ -871,7 +871,7 @@ echo 'HTML2PPTX_API_KEY=sk_live_xxxx' >> .env`,
         steps: [
           { title: 'Run the CLI command (recommended)', body: 'Add the hosted remote MCP server. OAuth authentication will start automatically.', code: `codex mcp add html2pptx --url https://html2pptx.app/mcp` },
           { title: 'Manual remote setup', body: 'If you only need hosted export tools, add the remote MCP server directly.', code: `codex mcp add html2pptx --url https://html2pptx.app/mcp` },
-          { title: 'Optional local stdio MCP for edit-slide', body: 'Use this only when Codex needs to launch local edit-slide for a `.html` file. It runs from the published package, so no repository checkout is required.', code: `codex mcp add html2pptx-local -- npx -y -p html2pptx-local-mcp@latest html2pptx-mcp` },
+          { title: 'Optional local stdio MCP for edit-slide', body: 'Use this only when Codex needs to launch local edit-slide for a `.html` file. It runs from the published package, so no repository checkout is required.', code: `codex mcp add html2pptx-local -- npx --yes --package html2pptx-local-mcp@latest html2pptx-mcp` },
           { title: 'Manual setup via codex.json', body: 'Alternatively, create or edit codex.json in your project root.', code: `{\n  "mcpServers": {\n    "html2pptx": {\n      "type": "url",\n      "url": "https://html2pptx.app/mcp"\n    }\n  }\n}` },
         ],
       },
@@ -1702,9 +1702,9 @@ echo 'HTML2PPTX_API_KEY=sk_live_xxxx' >> .env`,
         icon: 'https://cdn.jsdelivr.net/gh/glincker/thesvg@main/public/icons/claude/default.svg',
         recommended: true,
         steps: [
-          { title: 'Claude Codeユーザーはこの1行でOK', body: '`html2pptx` として remote export を登録し、`html2pptx-local` として local edit-slide を Claude Code の user config に直接書き込みます。', code: `npx -y -p html2pptx-local-mcp@latest html2pptx-install-mcp claude` },
+          { title: 'Claude Codeユーザーはこの1行でOK', body: '`html2pptx` として remote export を登録し、`html2pptx-local` として local edit-slide を Claude Code の user config に直接書き込みます。', code: `npx --yes --package html2pptx-local-mcp@latest html2pptx-install-mcp claude` },
           { title: 'remote だけ手動セットアップ', body: 'PPTX出力などのホスト側ツールだけ必要な場合はこちらを使います。', code: `claude mcp add --scope user --transport http html2pptx https://html2pptx.app/mcp` },
-          { title: 'local edit-slide 互換セットアップ', body: 'Claude Code の stdio 登録が不安定な場合も、このインストーラーが local server 設定を直接書き込みます。', code: `npx -y -p html2pptx-local-mcp@latest html2pptx-install-mcp claude` },
+          { title: 'local edit-slide 互換セットアップ', body: 'Claude Code の stdio 登録が不安定な場合も、このインストーラーが local server 設定を直接書き込みます。', code: `npx --yes --package html2pptx-local-mcp@latest html2pptx-install-mcp claude` },
         ],
         tip: 'このインストーラーは remote MCP を user scope で登録し、互換性のため local stdio MCP は Claude Code の user config に直接書き込みます。',
       },
@@ -1715,7 +1715,7 @@ echo 'HTML2PPTX_API_KEY=sk_live_xxxx' >> .env`,
         steps: [
           { title: 'CLIコマンドで追加（推奨）', body: 'hosted remote MCP server を追加します。OAuth認証が自動的に開始されます。', code: `codex mcp add html2pptx --url https://html2pptx.app/mcp` },
           { title: 'remote だけ手動セットアップ', body: 'PPTX出力などのホスト側ツールだけ必要な場合はこちらを使います。', code: `codex mcp add html2pptx --url https://html2pptx.app/mcp` },
-          { title: 'edit-slide 用 local stdio MCP（任意）', body: 'Codex がローカル `.html` を edit-slide で開く必要がある場合だけ追加します。公開パッケージから起動するため、リポジトリの checkout は不要です。', code: `codex mcp add html2pptx-local -- npx -y -p html2pptx-local-mcp@latest html2pptx-mcp` },
+          { title: 'edit-slide 用 local stdio MCP（任意）', body: 'Codex がローカル `.html` を edit-slide で開く必要がある場合だけ追加します。公開パッケージから起動するため、リポジトリの checkout は不要です。', code: `codex mcp add html2pptx-local -- npx --yes --package html2pptx-local-mcp@latest html2pptx-mcp` },
           { title: 'codex.json で手動セットアップ', body: 'コマンドが使えない場合は、プロジェクトルートの codex.json に以下を追加してください。', code: `{\n  "mcpServers": {\n    "html2pptx": {\n      "type": "url",\n      "url": "https://html2pptx.app/mcp"\n    }\n  }\n}` },
         ],
       },

package/cli/dist/commands/edit.js

@@ -2,14 +2,34 @@ import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
 import { spawn } from "node:child_process";
 import { createServer } from "node:http";
 import { platform } from "node:os";
-import { mkdir, readFile, realpath, stat, writeFile, } from "node:fs/promises";
+import { mkdir, readdir, readFile, realpath, stat, writeFile, } from "node:fs/promises";
 import { dirname, extname, join, relative, resolve, sep, } from "node:path";
 import * as p from "@clack/prompts";
 import pc from "picocolors";
 const AUTO_PORT = 0;
 const MAX_WRITE_BYTES = 5 * 1024 * 1024;
+const MAX_ASSET_BYTES = 8 * 1024 * 1024;
 const ALLOWED_EXTENSIONS = [".html", ".htm"];
 const ALLOWED_EXT = new Set(ALLOWED_EXTENSIONS);
+const ASSET_IMAGE_EXTENSIONS = [".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg", ".avif"];
+const ASSET_IMAGE_EXT = new Set(ASSET_IMAGE_EXTENSIONS);
+const ASSET_CONTENT_TYPES = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+    ".avif": "image/avif",
+};
+const ASSET_CONTENT_TYPE_EXT = {
+    "image/png": ".png",
+    "image/jpeg": ".jpg",
+    "image/gif": ".gif",
+    "image/webp": ".webp",
+    "image/svg+xml": ".svg",
+    "image/avif": ".avif",
+};
 const DISALLOWED_TOP_DIRECTORIES = [
     "public",
     ".next",
@@ -32,6 +52,9 @@ const EDITOR_BASE_URL_EXAMPLE = "http://localhost:<port>";
 function sha256(content) {
     return createHash("sha256").update(content).digest("hex");
 }
+function sha256Buffer(buf) {
+    return createHash("sha256").update(buf).digest("hex");
+}
 function generateSessionToken() {
     return randomBytes(32).toString("base64url");
 }
@@ -278,13 +301,13 @@ function validateWriteRequest(req, ctx, reqUrl) {
     return (req.headers["x-edit-slide-local"] === "1" ||
         req.headers["x-open-slide-local"] === "1");
 }
-async function readBody(req) {
+async function readBody(req, maxBytes = MAX_WRITE_BYTES) {
     const chunks = [];
     let total = 0;
     for await (const chunk of req) {
         const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
         total += buf.length;
-        if (total > MAX_WRITE_BYTES + 1024 * 1024) {
+        if (total > maxBytes + 1024 * 1024) {
             throw new Error("request body too large");
         }
         chunks.push(buf);
@@ -427,6 +450,182 @@ async function handlePost(ctx, req, res) {
         sendJson(res, 400, { error: error?.message || "write failed" });
     }
 }
+async function safeAssetPath(ctx, rel) {
+    if (typeof rel !== "string" || !rel) {
+        throw new Error("missing path");
+    }
+    const normalized = rel.replace(/^\/+/, "");
+    const abs = resolve(ctx.root, normalized);
+    if (abs !== ctx.root && !abs.startsWith(ctx.root + sep)) {
+        throw new Error("path escape");
+    }
+    const ext = extname(abs).toLowerCase();
+    if (!ASSET_IMAGE_EXT.has(ext)) {
+        throw new Error("only image files are allowed");
+    }
+    const real = await resolveReal(abs);
+    if (real !== ctx.root && !real.startsWith(ctx.root + sep)) {
+        throw new Error("path escape via symlink");
+    }
+    for (const candidate of [relative(ctx.root, abs), relative(ctx.root, real)]) {
+        const first = candidate.split(sep)[0];
+        if (DISALLOWED_TOP_DIRS.has(first)) {
+            throw new Error(`assets under ${first}/ are not allowed`);
+        }
+    }
+    return real;
+}
+function assetExt(name, contentType) {
+    const fromName = extname(String(name || "")).toLowerCase();
+    if (ASSET_IMAGE_EXT.has(fromName))
+        return fromName;
+    return ASSET_CONTENT_TYPE_EXT[String(contentType || "").toLowerCase()] || "";
+}
+function assetSlug(name) {
+    const base = String(name || "image").replace(/\.[^.]+$/, "");
+    const slug = base
+        .normalize("NFKD")
+        .replace(/[^\w.-]+/g, "-")
+        .replace(/^[-.]+|[-.]+$/g, "")
+        .toLowerCase();
+    return slug || "image";
+}
+function assetDirRel(scope, htmlDirRel) {
+    if (scope === "global")
+        return "assets";
+    return htmlDirRel ? join(htmlDirRel, "assets") : "assets";
+}
+async function readBytesOrNull(abs) {
+    try {
+        return await readFile(abs);
+    }
+    catch (error) {
+        if (error?.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+function sendBinary(res, status, contentType, buf) {
+    res.statusCode = status;
+    res.setHeader("content-type", contentType);
+    res.setHeader("cache-control", "no-store");
+    res.setHeader("x-content-type-options", "nosniff");
+    res.setHeader("content-security-policy", "sandbox; default-src 'none'; style-src 'unsafe-inline'");
+    res.end(buf);
+}
+async function handleAssetGet(ctx, req, reqUrl, res) {
+    if (!validateBridgeRequest(req, ctx, reqUrl)) {
+        sendJson(res, 403, { error: "forbidden" });
+        return;
+    }
+    const file = reqUrl.searchParams.get("file") || "";
+    const htmlDirRel = file ? dirname(file) : "";
+    if (reqUrl.searchParams.get("list") === "1") {
+        const scope = reqUrl.searchParams.get("scope") === "global" ? "global" : "project";
+        const dirRel = assetDirRel(scope, htmlDirRel);
+        const absDir = resolve(ctx.root, dirRel);
+        const htmlDirAbs = resolve(ctx.root, htmlDirRel || ".");
+        let assets = [];
+        try {
+            if (absDir === ctx.root || absDir.startsWith(ctx.root + sep)) {
+                const names = await readdir(absDir);
+                assets = names
+                    .filter((name) => ASSET_IMAGE_EXT.has(extname(name).toLowerCase()))
+                    .map((name) => ({
+                    name,
+                    src: toPosixPath(relative(htmlDirAbs, join(absDir, name))),
+                }));
+            }
+        }
+        catch {
+            assets = [];
+        }
+        sendJson(res, 200, { assets, policy: buildPolicy(ctx) });
+        return;
+    }
+    const src = reqUrl.searchParams.get("src") || "";
+    if (!src) {
+        sendJson(res, 400, { error: "missing src" });
+        return;
+    }
+    try {
+        const abs = await safeAssetPath(ctx, join(htmlDirRel, src));
+        const buf = await readFile(abs);
+        const ext = extname(abs).toLowerCase();
+        sendBinary(res, 200, ASSET_CONTENT_TYPES[ext] || "application/octet-stream", buf);
+    }
+    catch (error) {
+        const message = error?.message || "read failed";
+        const status = message.includes("ENOENT") ? 404 : 400;
+        sendJson(res, status, { error: message });
+    }
+}
+async function handleAssetPost(ctx, req, res) {
+    const reqUrl = new URL(req.url || "/", `http://${req.headers.host || "127.0.0.1"}`);
+    if (!validateWriteRequest(req, ctx, reqUrl)) {
+        sendJson(res, 403, { error: "forbidden" });
+        return;
+    }
+    let body;
+    try {
+        body = JSON.parse(await readBody(req, MAX_ASSET_BYTES * 2));
+    }
+    catch (error) {
+        sendJson(res, 400, { error: error?.message || "invalid json" });
+        return;
+    }
+    const { file, scope: rawScope, name, contentType, dataBase64 } = body || {};
+    if (typeof dataBase64 !== "string" || !dataBase64) {
+        sendJson(res, 400, { error: "missing image data" });
+        return;
+    }
+    const buf = Buffer.from(dataBase64, "base64");
+    if (!buf.length) {
+        sendJson(res, 400, { error: "empty image data" });
+        return;
+    }
+    if (buf.length > MAX_ASSET_BYTES) {
+        sendJson(res, 413, { error: "image too large (>8MB)" });
+        return;
+    }
+    const ext = assetExt(name, contentType);
+    if (!ASSET_IMAGE_EXT.has(ext)) {
+        sendJson(res, 400, { error: "unsupported image type" });
+        return;
+    }
+    const scope = rawScope === "global" ? "global" : "project";
+    const htmlDirRel = typeof file === "string" && file ? dirname(file) : "";
+    const htmlDirAbs = resolve(ctx.root, htmlDirRel || ".");
+    const dirRel = assetDirRel(scope, htmlDirRel);
+    const slug = assetSlug(name);
+    try {
+        let fileName = `${slug}${ext}`;
+        let absTarget = await safeAssetPath(ctx, join(dirRel, fileName));
+        const existing = await readBytesOrNull(absTarget);
+        if (existing && !existing.equals(buf)) {
+            fileName = `${slug}-${sha256Buffer(buf).slice(0, 8)}${ext}`;
+            absTarget = await safeAssetPath(ctx, join(dirRel, fileName));
+        }
+        const alreadyIdentical = Boolean(existing && existing.equals(buf));
+        if (!alreadyIdentical) {
+            await mkdir(dirname(absTarget), { recursive: true });
+            await writeFile(absTarget, buf);
+        }
+        sendJson(res, 200, {
+            ok: true,
+            scope,
+            name: fileName,
+            path: toPosixPath(relative(ctx.root, absTarget)),
+            src: toPosixPath(relative(htmlDirAbs, absTarget)),
+            bytes: buf.length,
+            reused: alreadyIdentical,
+            policy: buildPolicy(ctx),
+        });
+    }
+    catch (error) {
+        sendJson(res, 400, { error: error?.message || "asset write failed" });
+    }
+}
 function createBridgeServer(ctx) {
     return createServer(async (req, res) => {
         if (!applyCors(req, res, ctx.editorOrigin))
@@ -445,6 +644,18 @@ function createBridgeServer(ctx) {
             sendJson(res, 200, { ok: true, service: "html2pptx edit bridge", root: ctx.root });
             return;
         }
+        if (reqUrl.pathname === "/api/edit-slide/asset") {
+            if (req.method === "GET") {
+                await handleAssetGet(ctx, req, reqUrl, res);
+                return;
+            }
+            if (req.method === "POST") {
+                await handleAssetPost(ctx, req, res);
+                return;
+            }
+            sendJson(res, 405, { error: "method not allowed" });
+            return;
+        }
         if (reqUrl.pathname !== "/api/edit-slide/file") {
             sendJson(res, 404, { error: "not found" });
             return;

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "html2pptx-local-mcp",
-  "version": "1.1.19",
+  "version": "1.1.20",
   "type": "module",
   "description": "Local stdio MCP server for opening html2pptx slide HTML in the local edit-slide editor.",
   "bin": {
     "html2pptx-mcp": "./mcp/pptx-studio-mcp-server.mjs",
-    "html2pptx-install-mcp": "./scripts/install-mcp.mjs"
+    "html2pptx-install-mcp": "./scripts/install-mcp.mjs",
+    "html2pptx-comments": "./scripts/extract-html2pptx-comments.mjs"
   },
   "files": [
     "app/docs/content.js",
@@ -16,6 +17,7 @@
     "lib/server/template-html-policy.mjs",
     "mcp/pptx-studio-mcp-server.mjs",
     "scripts/install-mcp.mjs",
+    "scripts/extract-html2pptx-comments.mjs",
     "src/animation-injector.js",
     "src/animation-renderers.js"
   ],

package/scripts/extract-html2pptx-comments.mjs

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+
+import { readFile } from 'node:fs/promises';
+import { extname, resolve } from 'node:path';
+import { JSDOM } from 'jsdom';
+
+const ALLOWED_EXTENSIONS = new Set(['.html', '.htm']);
+
+function usage() {
+  return [
+    'Usage: html2pptx-comments <file.html> [--json|--format markdown|--format json]',
+    '',
+    'Extracts edit-slide element comments saved as data-html2pptx-comment attributes.',
+  ].join('\n');
+}
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  let file = '';
+  let format = 'markdown';
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--help' || arg === '-h') {
+      return { help: true, file, format };
+    }
+    if (arg === '--json') {
+      format = 'json';
+      continue;
+    }
+    if (arg === '--format') {
+      const value = args[i + 1];
+      if (!['json', 'markdown'].includes(value)) {
+        throw new Error('--format must be "json" or "markdown".');
+      }
+      format = value;
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith('-')) {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+    if (file) {
+      throw new Error(`Unexpected extra file argument: ${arg}`);
+    }
+    file = arg;
+  }
+  return { help: false, file, format };
+}
+
+function cssEscape(value) {
+  return String(value).replace(/[^a-zA-Z0-9_-]/g, (char) => `\\${char}`);
+}
+
+function shortText(value, max = 80) {
+  const text = String(value || '').trim().replace(/\s+/g, ' ');
+  return text.length > max ? `${text.slice(0, max - 1)}...` : text;
+}
+
+function elementLabel(element) {
+  const tag = element.tagName.toLowerCase();
+  const named =
+    element.getAttribute('data-layer-name') ||
+    element.getAttribute('data-name') ||
+    element.getAttribute('aria-label') ||
+    element.getAttribute('alt') ||
+    shortText(element.textContent, 48);
+  return named ? `${tag}: ${named}` : tag;
+}
+
+function cssPath(element, root) {
+  if (!element || element === root) return '';
+  const parts = [];
+  let node = element;
+  while (node && node !== root && node.nodeType === 1) {
+    const tag = node.tagName.toLowerCase();
+    const id = node.getAttribute('id');
+    if (id) {
+      parts.unshift(`${tag}#${cssEscape(id)}`);
+      break;
+    }
+    const className = node.getAttribute('class');
+    const classes = className ? className.split(/\s+/).filter(Boolean).slice(0, 2).map(cssEscape) : [];
+    const classPart = classes.length ? `.${classes.join('.')}` : '';
+    const siblings = Array.from(node.parentElement?.children || []).filter((child) => child.tagName === node.tagName);
+    const indexPart = siblings.length > 1 ? `:nth-of-type(${siblings.indexOf(node) + 1})` : '';
+    parts.unshift(`${tag}${classPart}${indexPart}`);
+    node = node.parentElement;
+  }
+  return parts.join(' > ');
+}
+
+function extractComments(html, filePath) {
+  const dom = new JSDOM(html);
+  const document = dom.window.document;
+  const slides = Array.from(document.querySelectorAll('section.slide'));
+  const commented = Array.from(document.querySelectorAll('[data-html2pptx-comment]'));
+  return commented
+    .map((element, index) => {
+      const comment = shortText(element.getAttribute('data-html2pptx-comment'), 2000);
+      if (!comment) return null;
+      const slideElement = element.closest('section.slide');
+      const slideIndex = slideElement ? slides.indexOf(slideElement) : -1;
+      const root = slideElement || document.body;
+      const selector = element.getAttribute('data-html2pptx-comment-selector') || cssPath(element, root) || '__root__';
+      return {
+        index: index + 1,
+        file: filePath,
+        slide: slideIndex >= 0 ? slideIndex + 1 : null,
+        id: element.getAttribute('data-html2pptx-comment-id') || null,
+        selector,
+        tag: element.tagName.toLowerCase(),
+        label: elementLabel(element),
+        comment,
+        updatedAt: element.getAttribute('data-html2pptx-comment-updated-at') || null,
+      };
+    })
+    .filter(Boolean);
+}
+
+function formatMarkdown(filePath, comments) {
+  if (!comments.length) {
+    return `No html2pptx comments found in ${filePath}.`;
+  }
+  const lines = [
+    `# html2pptx comments`,
+    '',
+    `File: \`${filePath}\``,
+    `Count: ${comments.length}`,
+    '',
+  ];
+  for (const item of comments) {
+    lines.push(
+      `## ${item.index}. ${item.slide ? `Slide ${item.slide}` : 'Document'} / ${item.label}`,
+      '',
+      `- selector: \`${item.selector}\``,
+      item.id ? `- id: \`${item.id}\`` : null,
+      item.updatedAt ? `- updated: ${item.updatedAt}` : null,
+      '',
+      item.comment,
+      '',
+    );
+  }
+  return lines.filter((line) => line !== null).join('\n');
+}
+
+async function main() {
+  const { help, file, format } = parseArgs(process.argv);
+  if (help) {
+    console.log(usage());
+    return;
+  }
+  if (!file) {
+    throw new Error(`Missing file.\n\n${usage()}`);
+  }
+  const filePath = resolve(file);
+  const ext = extname(filePath).toLowerCase();
+  if (!ALLOWED_EXTENSIONS.has(ext)) {
+    throw new Error('Only .html and .htm files are supported.');
+  }
+  const html = await readFile(filePath, 'utf8');
+  const comments = extractComments(html, filePath);
+  if (format === 'json') {
+    console.log(JSON.stringify({ file: filePath, count: comments.length, comments }, null, 2));
+  } else {
+    console.log(formatMarkdown(filePath, comments));
+  }
+}
+
+main().catch((error) => {
+  console.error(error?.message || String(error));
+  process.exitCode = 1;
+});

package/scripts/install-mcp.mjs

@@ -2,7 +2,7 @@
 
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 
 const REMOTE_SERVER_NAME = 'html2pptx';
 const LOCAL_SERVER_NAME = 'html2pptx-local';
@@ -13,6 +13,7 @@ const args = process.argv.slice(2);
 const dryRun = args.includes('--dry-run');
 const help = args.includes('--help') || args.includes('-h');
 const client = resolveClient(args);
+const localCommand = buildLocalMcpCommand();
 
 if (help) {
   printHelp();
@@ -29,7 +30,7 @@ const steps = buildSteps(client);
 
 console.log(`Installing html2pptx MCP for ${client}.`);
 console.log(`Remote server: ${REMOTE_SERVER_NAME} -> ${REMOTE_MCP_URL}`);
-console.log(`Local server:  ${LOCAL_SERVER_NAME} -> npx -y -p ${LOCAL_PACKAGE_SPEC} html2pptx-mcp`);
+console.log(`Local server:  ${LOCAL_SERVER_NAME} -> ${renderCommand(localCommand.command, localCommand.args)}`);
 console.log('');
 
 for (const step of steps) {
@@ -89,11 +90,8 @@ function buildSteps(targetClient) {
         'add',
         LOCAL_SERVER_NAME,
         '--',
-        'npx',
-        '-y',
-        '-p',
-        LOCAL_PACKAGE_SPEC,
-        'html2pptx-mcp',
+        localCommand.command,
+        ...localCommand.args,
       ],
     },
   ];
@@ -103,8 +101,8 @@ function writeClaudeLocalMcpConfig() {
   const configPath = join(process.env.HOME || process.cwd(), '.claude.json');
   const serverConfig = {
     type: 'stdio',
-    command: 'npx',
-    args: ['-y', '-p', LOCAL_PACKAGE_SPEC, 'html2pptx-mcp'],
+    command: localCommand.command,
+    args: localCommand.args,
     env: {},
   };
 
@@ -135,6 +133,27 @@ function writeClaudeLocalMcpConfig() {
   console.log(`Registered local MCP server ${LOCAL_SERVER_NAME} in Claude user config.`);
 }
 
+export function buildLocalMcpCommand(env = process.env) {
+  const npmExecPath = env.npm_execpath || env.npm_execPath;
+  const npxCli = npmExecPath ? join(dirname(npmExecPath), 'npx-cli.js') : '';
+
+  if (npxCli && existsSync(npxCli)) {
+    return {
+      command: process.execPath,
+      args: [npxCli, '--yes', '--package', LOCAL_PACKAGE_SPEC, 'html2pptx-mcp'],
+    };
+  }
+
+  return {
+    command: 'npx',
+    args: ['--yes', '--package', LOCAL_PACKAGE_SPEC, 'html2pptx-mcp'],
+  };
+}
+
+function renderCommand(command, args) {
+  return [command, ...args].join(' ');
+}
+
 function runStep(step) {
   const rendered = [step.command, ...step.args].join(' ');
   console.log(`> ${rendered}`);
@@ -179,8 +198,8 @@ Usage:
   html2pptx-install-mcp --client codex
 
 Examples:
-  npx -y -p html2pptx-local-mcp@latest html2pptx-install-mcp claude
-  npx -y -p html2pptx-local-mcp@latest html2pptx-install-mcp codex
+  npx --yes --package html2pptx-local-mcp@latest html2pptx-install-mcp claude
+  npx --yes --package html2pptx-local-mcp@latest html2pptx-install-mcp codex
 
 Optional:
   HTML2PPTX_LOCAL_MCP_PACKAGE_SPEC=<package-or-tarball> html2pptx-install-mcp claude