pptx-viewer-mcp 1.1.0

package/README.md

@@ -0,0 +1,146 @@
+# pptx-viewer-mcp
+
+Pure tool functions, Zod schemas, a Y.Doc collaboration codec, and an MCP server for PPTX manipulation — all built on top of `pptx-viewer-core`.
+
+## Installation
+
+```sh
+npm install pptx-viewer-mcp pptx-viewer-core
+# optional — required only for the collaboration codec
+npm install yjs
+```
+
+## Exports
+
+| Entry point                  | Contents                                                |
+| ---------------------------- | ------------------------------------------------------- |
+| `pptx-viewer-mcp`         | 24 tool functions + provider types + execution pipeline |
+| `pptx-viewer-mcp/schemas` | Zod schemas for every tool input                        |
+| `pptx-viewer-mcp/codec`   | `PptxCodec` — Y.Doc ↔ PPTX bytes codec                  |
+| `pptx-viewer-mcp/mcp`     | `createServer()` — programmatic MCP server factory      |
+
+## Tool reference
+
+**Slide (8):** `getSlide`, `addSlide`, `deleteSlides`, `reorderSlides`, `duplicateSlide`, `updateSlideProperties`, `setSlideTransition`, `setCanvasSize`
+
+**Element (9):** `addElement`, `updateElement`, `deleteElements`, `arrangeElements`, `cloneElement`, `setElementAnimation`, `groupElements`, `ungroupElements`, `batchUpdateElements`
+
+**Table (2):** `updateTableCells`, `manageTableStructure`
+
+**Style (2):** `updateElementStyle`, `runAccessibilityCheck`
+
+**Content (3):** `findText`, `replaceText`, `manageComments`
+
+**Conversion (1):** `convertToMarkdown`
+
+---
+
+## Quick start
+
+### 1. Using tool functions directly
+
+Every tool is a pure function — no file I/O, no framework dependencies.
+
+```ts
+import { PptxHandler } from 'pptx-viewer-core';
+import { addSlide, getSlide } from 'pptx-viewer-mcp';
+
+// Load
+const handler = new PptxHandler();
+const bytes = await fs.readFile('deck.pptx');
+const pptxData = await handler.load(bytes.buffer);
+
+// Run a tool
+const ctx = { pptxData };
+const { pptxData: updated, dirty } = addSlide(ctx, { insertAfterIndex: 0 });
+
+// Save when dirty
+if (dirty) {
+	const out = await handler.save(updated.slides);
+	await fs.writeFile('deck.pptx', out);
+}
+
+// Inspect a slide
+const { result } = getSlide(ctx, { slideIndex: 0 });
+console.log(result.elements);
+```
+
+### 2. Using the MCP server
+
+Add to your MCP client configuration (Claude Desktop, Cursor, etc.):
+
+```json
+{
+	"mcpServers": {
+		"pptx": {
+			"command": "npx",
+			"args": ["pptx-viewer-mcp"]
+		}
+	}
+}
+```
+
+The binary is also available as `pptx-tools` after a global install. All 24 tools are exposed over stdio with the same names in snake_case (e.g. `add_slide`, `batch_update_elements`). Every tool accepts a `filePath` parameter — the server handles load/save internally.
+
+### 3. Using `executeToolWithContext` with providers
+
+`executeToolWithContext` wraps the load → tool → save cycle and routes through a live Y.Doc collaboration room when one is available.
+
+```ts
+import {
+	executeToolWithContext,
+	type ExecutionContext,
+	type FileSystemProvider,
+	type CollaborationProvider,
+} from 'pptx-viewer-mcp';
+import { replaceText } from 'pptx-viewer-mcp';
+import { readFile, writeFile } from 'node:fs/promises';
+
+// Minimal file-system-only provider
+const filesystem: FileSystemProvider = {
+	readFile: (p) => readFile(p),
+	writeFile: (p, data) => writeFile(p, data),
+};
+
+const execCtx: ExecutionContext = { filesystem };
+
+const result = await executeToolWithContext('deck.pptx', execCtx, (ctx) =>
+	replaceText(ctx, { find: 'Draft', replace: 'Final', caseSensitive: false }),
+);
+
+console.log(result.replacements, result.savedToDisk);
+```
+
+When `execCtx.collaboration` is provided, `executeToolWithContext` automatically dehydrates the current Y.Doc state before running the tool and re-hydrates the room after saving, so remote peers receive the change without a file reload.
+
+---
+
+## Architecture
+
+```
+ToolContext { pptxData }
+        │
+        ▼
+tool function  →  ToolResult { pptxData, result, dirty }
+                        │
+                        ▼  (when dirty)
+              savePresentation()
+                ├─ collaboration room → hydrate Y.Doc → broadcast
+                └─ no room → writeFile to disk
+```
+
+`CollaborationProvider`, `FileSystemProvider`, and `ViewerProvider` are plain interfaces — implement them for any runtime (Node, Electron, browser, edge worker).
+
+---
+
+## Development
+
+```sh
+bun run build      # tsup → dist/
+bun run typecheck  # tsc --noEmit
+bun run test       # vitest run
+```
+
+## License
+
+MIT

package/dist/codec/index.d.mts

@@ -0,0 +1,26 @@
+import { Doc } from 'yjs';
+
+declare const ORIGIN_FILE_LOAD = "file-load";
+/**
+ * Bidirectional format codec: file bytes <-> Y.Doc shared types.
+ */
+interface FormatCodec {
+    readonly formatId: string;
+    readonly extensions: string[];
+    hydrate(ydoc: Doc, bytes: Uint8Array, origin?: string): Promise<void>;
+    dehydrate(ydoc: Doc, dirtyPaths?: string[]): Promise<Uint8Array>;
+    observe(ydoc: Doc, onChange: () => void): () => void;
+}
+declare class PptxCodec implements FormatCodec {
+    readonly formatId = "pptx";
+    readonly extensions: string[];
+    hydrate(ydoc: Doc, bytes: Uint8Array, origin?: string): Promise<void>;
+    dehydrate(ydoc: Doc, _dirtyPaths?: string[]): Promise<Uint8Array>;
+    observe(ydoc: Doc, onChange: () => void): () => void;
+    private _slideToYMap;
+    private _yMapToSlide;
+    private _elementToYMap;
+    private _yMapToElement;
+}
+
+export { type FormatCodec, ORIGIN_FILE_LOAD, PptxCodec };

package/dist/codec/index.d.ts

@@ -0,0 +1,26 @@
+import { Doc } from 'yjs';
+
+declare const ORIGIN_FILE_LOAD = "file-load";
+/**
+ * Bidirectional format codec: file bytes <-> Y.Doc shared types.
+ */
+interface FormatCodec {
+    readonly formatId: string;
+    readonly extensions: string[];
+    hydrate(ydoc: Doc, bytes: Uint8Array, origin?: string): Promise<void>;
+    dehydrate(ydoc: Doc, dirtyPaths?: string[]): Promise<Uint8Array>;
+    observe(ydoc: Doc, onChange: () => void): () => void;
+}
+declare class PptxCodec implements FormatCodec {
+    readonly formatId = "pptx";
+    readonly extensions: string[];
+    hydrate(ydoc: Doc, bytes: Uint8Array, origin?: string): Promise<void>;
+    dehydrate(ydoc: Doc, _dirtyPaths?: string[]): Promise<Uint8Array>;
+    observe(ydoc: Doc, onChange: () => void): () => void;
+    private _slideToYMap;
+    private _yMapToSlide;
+    private _elementToYMap;
+    private _yMapToElement;
+}
+
+export { type FormatCodec, ORIGIN_FILE_LOAD, PptxCodec };

package/dist/codec/index.js

@@ -0,0 +1,241 @@
+'use strict';
+
+var pptxViewerCore = require('pptx-viewer-core');
+var yjs = require('yjs');
+
+// src/codec/pptx-codec.ts
+var ORIGIN_FILE_LOAD = "file-load";
+var SCALAR_ELEMENT_KEYS = /* @__PURE__ */ new Set([
+  "id",
+  "type",
+  "x",
+  "y",
+  "width",
+  "height",
+  "rotation",
+  "flipHorizontal",
+  "flipVertical",
+  "hidden",
+  "opacity",
+  "text",
+  "name",
+  "altText",
+  "shapeType",
+  "placeholder",
+  "imagePath",
+  "imageData",
+  "svgContent",
+  "inkSvg",
+  "sourceSlideId",
+  "mediaType",
+  "mediaPath",
+  "linkedTxbxId",
+  "linkedTxbxSeq",
+  "promptText"
+]);
+var COMPLEX_FIELD_MAP = {
+  textSegments: "_textSegments",
+  textStyle: "_textStyle",
+  shapeStyle: "_shapeStyle",
+  shapeAdjustments: "_shapeAdjustments",
+  adjustmentHandles: "_adjustmentHandles",
+  tableData: "_tableData",
+  chartData: "_chartData",
+  smartArtData: "_smartArtData",
+  connectionStart: "_connectionStart",
+  connectionEnd: "_connectionEnd",
+  animations: "_animations",
+  nativeAnimations: "_nativeAnimations",
+  children: "_children",
+  paragraphIndents: "_paragraphIndents",
+  rawXml: "_rawXml",
+  actionClick: "_actionClick",
+  actionHover: "_actionHover",
+  locks: "_locks",
+  imageEffects: "_imageEffects",
+  cropShape: "_cropShape",
+  mediaBookmarks: "_mediaBookmarks",
+  captionTracks: "_captionTracks"
+};
+var REVERSE_COMPLEX_MAP = {};
+for (const [original, prefixed] of Object.entries(COMPLEX_FIELD_MAP)) {
+  REVERSE_COMPLEX_MAP[prefixed] = original;
+}
+var SCALAR_SLIDE_KEYS = /* @__PURE__ */ new Set([
+  "id",
+  "rId",
+  "sourceSlideId",
+  "layoutPath",
+  "layoutName",
+  "slideNumber",
+  "hidden",
+  "sectionName",
+  "sectionId",
+  "backgroundColor",
+  "backgroundImage",
+  "backgroundGradient",
+  "notes",
+  "backgroundShowAnimation",
+  "showMasterShapes",
+  "isDirty"
+]);
+var COMPLEX_SLIDE_FIELD_MAP = {
+  transition: "_transition",
+  animations: "_animations",
+  nativeAnimations: "_nativeAnimations",
+  rawTiming: "_rawTiming",
+  notesSegments: "_notesSegments",
+  comments: "_comments",
+  warnings: "_warnings",
+  rawXml: "_rawXml",
+  clrMapOverride: "_clrMapOverride",
+  guides: "_guides",
+  customerData: "_customerData",
+  activeXControls: "_activeXControls"
+};
+var REVERSE_COMPLEX_SLIDE_MAP = {};
+for (const [original, prefixed] of Object.entries(COMPLEX_SLIDE_FIELD_MAP)) {
+  REVERSE_COMPLEX_SLIDE_MAP[prefixed] = original;
+}
+var PptxCodec = class {
+  formatId = "pptx";
+  extensions = [".pptx", ".ppt"];
+  async hydrate(ydoc, bytes, origin) {
+    const effectiveOrigin = origin ?? ORIGIN_FILE_LOAD;
+    const handler = new pptxViewerCore.PptxHandler();
+    const pptxData = await handler.load(bytes.buffer);
+    ydoc.transact(() => {
+      const meta = ydoc.getMap("pptx:meta");
+      meta.set("width", pptxData.width);
+      meta.set("height", pptxData.height);
+      if (pptxData.widthEmu !== void 0) {
+        meta.set("widthEmu", pptxData.widthEmu);
+      }
+      if (pptxData.heightEmu !== void 0) {
+        meta.set("heightEmu", pptxData.heightEmu);
+      }
+      const sourceBytesArr = new yjs.Array();
+      sourceBytesArr.insert(0, Array.from(bytes));
+      meta.set("sourceBytes", sourceBytesArr);
+      const slidesArray = ydoc.getArray("pptx:slides");
+      if (slidesArray.length > 0) {
+        slidesArray.delete(0, slidesArray.length);
+      }
+      for (const slide of pptxData.slides) {
+        const slideMap = this._slideToYMap(slide);
+        slidesArray.push([slideMap]);
+      }
+    }, effectiveOrigin);
+  }
+  async dehydrate(ydoc, _dirtyPaths) {
+    const meta = ydoc.getMap("pptx:meta");
+    const slidesArray = ydoc.getArray("pptx:slides");
+    const slides = [];
+    for (let i = 0; i < slidesArray.length; i++) {
+      const slideMap = slidesArray.get(i);
+      slides.push(this._yMapToSlide(slideMap));
+    }
+    const sourceBytesArr = meta.get("sourceBytes");
+    try {
+      if (!sourceBytesArr || sourceBytesArr.length === 0) {
+        throw new Error("No source bytes for PptxHandler");
+      }
+      const sourceBytes = new Uint8Array(sourceBytesArr.toArray());
+      const handler = new pptxViewerCore.PptxHandler();
+      await handler.load(sourceBytes.buffer);
+      return await handler.save(slides);
+    } catch {
+      if (sourceBytesArr && sourceBytesArr.length > 0) {
+        return new Uint8Array(sourceBytesArr.toArray());
+      }
+      throw new Error("No PPTX bytes available for dehydration");
+    }
+  }
+  observe(ydoc, onChange) {
+    const slidesArray = ydoc.getArray("pptx:slides");
+    const meta = ydoc.getMap("pptx:meta");
+    const handler = () => onChange();
+    slidesArray.observeDeep(handler);
+    meta.observeDeep(handler);
+    return () => {
+      slidesArray.unobserveDeep(handler);
+      meta.unobserveDeep(handler);
+    };
+  }
+  _slideToYMap(slide) {
+    const slideMap = new yjs.Map();
+    const slideRecord = slide;
+    for (const key of SCALAR_SLIDE_KEYS) {
+      const value = slideRecord[key];
+      if (value !== void 0) {
+        slideMap.set(key, value);
+      }
+    }
+    for (const [original, prefixed] of Object.entries(COMPLEX_SLIDE_FIELD_MAP)) {
+      const value = slideRecord[original];
+      if (value !== void 0) {
+        slideMap.set(prefixed, JSON.stringify(value));
+      }
+    }
+    const elementsArray = new yjs.Array();
+    for (const element of slide.elements) {
+      elementsArray.push([this._elementToYMap(element)]);
+    }
+    slideMap.set("elements", elementsArray);
+    return slideMap;
+  }
+  _yMapToSlide(slideMap) {
+    const slide = {};
+    for (const key of SCALAR_SLIDE_KEYS) {
+      const value = slideMap.get(key);
+      if (value !== void 0) {
+        slide[key] = value;
+      }
+    }
+    for (const [prefixed, original] of Object.entries(REVERSE_COMPLEX_SLIDE_MAP)) {
+      const value = slideMap.get(prefixed);
+      if (value !== void 0) {
+        slide[original] = JSON.parse(value);
+      }
+    }
+    const elementsArray = slideMap.get("elements");
+    const elements = [];
+    if (elementsArray) {
+      for (let i = 0; i < elementsArray.length; i++) {
+        const elemMap = elementsArray.get(i);
+        elements.push(this._yMapToElement(elemMap));
+      }
+    }
+    slide["elements"] = elements;
+    return slide;
+  }
+  _elementToYMap(element) {
+    const elemMap = new yjs.Map();
+    const record = element;
+    for (const [key, value] of Object.entries(record)) {
+      if (value === void 0) {
+        continue;
+      }
+      if (SCALAR_ELEMENT_KEYS.has(key)) {
+        elemMap.set(key, value);
+      } else if (COMPLEX_FIELD_MAP[key]) {
+        elemMap.set(COMPLEX_FIELD_MAP[key], JSON.stringify(value));
+      }
+    }
+    return elemMap;
+  }
+  _yMapToElement(elemMap) {
+    const element = {};
+    elemMap.forEach((value, key) => {
+      if (REVERSE_COMPLEX_MAP[key]) {
+        element[REVERSE_COMPLEX_MAP[key]] = JSON.parse(value);
+      } else {
+        element[key] = value;
+      }
+    });
+    return element;
+  }
+};
+
+exports.ORIGIN_FILE_LOAD = ORIGIN_FILE_LOAD;
+exports.PptxCodec = PptxCodec;

package/dist/codec/index.mjs

@@ -0,0 +1,238 @@
+import { PptxHandler } from 'pptx-viewer-core';
+import { Array as Array$1, Map } from 'yjs';
+
+// src/codec/pptx-codec.ts
+var ORIGIN_FILE_LOAD = "file-load";
+var SCALAR_ELEMENT_KEYS = /* @__PURE__ */ new Set([
+  "id",
+  "type",
+  "x",
+  "y",
+  "width",
+  "height",
+  "rotation",
+  "flipHorizontal",
+  "flipVertical",
+  "hidden",
+  "opacity",
+  "text",
+  "name",
+  "altText",
+  "shapeType",
+  "placeholder",
+  "imagePath",
+  "imageData",
+  "svgContent",
+  "inkSvg",
+  "sourceSlideId",
+  "mediaType",
+  "mediaPath",
+  "linkedTxbxId",
+  "linkedTxbxSeq",
+  "promptText"
+]);
+var COMPLEX_FIELD_MAP = {
+  textSegments: "_textSegments",
+  textStyle: "_textStyle",
+  shapeStyle: "_shapeStyle",
+  shapeAdjustments: "_shapeAdjustments",
+  adjustmentHandles: "_adjustmentHandles",
+  tableData: "_tableData",
+  chartData: "_chartData",
+  smartArtData: "_smartArtData",
+  connectionStart: "_connectionStart",
+  connectionEnd: "_connectionEnd",
+  animations: "_animations",
+  nativeAnimations: "_nativeAnimations",
+  children: "_children",
+  paragraphIndents: "_paragraphIndents",
+  rawXml: "_rawXml",
+  actionClick: "_actionClick",
+  actionHover: "_actionHover",
+  locks: "_locks",
+  imageEffects: "_imageEffects",
+  cropShape: "_cropShape",
+  mediaBookmarks: "_mediaBookmarks",
+  captionTracks: "_captionTracks"
+};
+var REVERSE_COMPLEX_MAP = {};
+for (const [original, prefixed] of Object.entries(COMPLEX_FIELD_MAP)) {
+  REVERSE_COMPLEX_MAP[prefixed] = original;
+}
+var SCALAR_SLIDE_KEYS = /* @__PURE__ */ new Set([
+  "id",
+  "rId",
+  "sourceSlideId",
+  "layoutPath",
+  "layoutName",
+  "slideNumber",
+  "hidden",
+  "sectionName",
+  "sectionId",
+  "backgroundColor",
+  "backgroundImage",
+  "backgroundGradient",
+  "notes",
+  "backgroundShowAnimation",
+  "showMasterShapes",
+  "isDirty"
+]);
+var COMPLEX_SLIDE_FIELD_MAP = {
+  transition: "_transition",
+  animations: "_animations",
+  nativeAnimations: "_nativeAnimations",
+  rawTiming: "_rawTiming",
+  notesSegments: "_notesSegments",
+  comments: "_comments",
+  warnings: "_warnings",
+  rawXml: "_rawXml",
+  clrMapOverride: "_clrMapOverride",
+  guides: "_guides",
+  customerData: "_customerData",
+  activeXControls: "_activeXControls"
+};
+var REVERSE_COMPLEX_SLIDE_MAP = {};
+for (const [original, prefixed] of Object.entries(COMPLEX_SLIDE_FIELD_MAP)) {
+  REVERSE_COMPLEX_SLIDE_MAP[prefixed] = original;
+}
+var PptxCodec = class {
+  formatId = "pptx";
+  extensions = [".pptx", ".ppt"];
+  async hydrate(ydoc, bytes, origin) {
+    const effectiveOrigin = origin ?? ORIGIN_FILE_LOAD;
+    const handler = new PptxHandler();
+    const pptxData = await handler.load(bytes.buffer);
+    ydoc.transact(() => {
+      const meta = ydoc.getMap("pptx:meta");
+      meta.set("width", pptxData.width);
+      meta.set("height", pptxData.height);
+      if (pptxData.widthEmu !== void 0) {
+        meta.set("widthEmu", pptxData.widthEmu);
+      }
+      if (pptxData.heightEmu !== void 0) {
+        meta.set("heightEmu", pptxData.heightEmu);
+      }
+      const sourceBytesArr = new Array$1();
+      sourceBytesArr.insert(0, Array.from(bytes));
+      meta.set("sourceBytes", sourceBytesArr);
+      const slidesArray = ydoc.getArray("pptx:slides");
+      if (slidesArray.length > 0) {
+        slidesArray.delete(0, slidesArray.length);
+      }
+      for (const slide of pptxData.slides) {
+        const slideMap = this._slideToYMap(slide);
+        slidesArray.push([slideMap]);
+      }
+    }, effectiveOrigin);
+  }
+  async dehydrate(ydoc, _dirtyPaths) {
+    const meta = ydoc.getMap("pptx:meta");
+    const slidesArray = ydoc.getArray("pptx:slides");
+    const slides = [];
+    for (let i = 0; i < slidesArray.length; i++) {
+      const slideMap = slidesArray.get(i);
+      slides.push(this._yMapToSlide(slideMap));
+    }
+    const sourceBytesArr = meta.get("sourceBytes");
+    try {
+      if (!sourceBytesArr || sourceBytesArr.length === 0) {
+        throw new Error("No source bytes for PptxHandler");
+      }
+      const sourceBytes = new Uint8Array(sourceBytesArr.toArray());
+      const handler = new PptxHandler();
+      await handler.load(sourceBytes.buffer);
+      return await handler.save(slides);
+    } catch {
+      if (sourceBytesArr && sourceBytesArr.length > 0) {
+        return new Uint8Array(sourceBytesArr.toArray());
+      }
+      throw new Error("No PPTX bytes available for dehydration");
+    }
+  }
+  observe(ydoc, onChange) {
+    const slidesArray = ydoc.getArray("pptx:slides");
+    const meta = ydoc.getMap("pptx:meta");
+    const handler = () => onChange();
+    slidesArray.observeDeep(handler);
+    meta.observeDeep(handler);
+    return () => {
+      slidesArray.unobserveDeep(handler);
+      meta.unobserveDeep(handler);
+    };
+  }
+  _slideToYMap(slide) {
+    const slideMap = new Map();
+    const slideRecord = slide;
+    for (const key of SCALAR_SLIDE_KEYS) {
+      const value = slideRecord[key];
+      if (value !== void 0) {
+        slideMap.set(key, value);
+      }
+    }
+    for (const [original, prefixed] of Object.entries(COMPLEX_SLIDE_FIELD_MAP)) {
+      const value = slideRecord[original];
+      if (value !== void 0) {
+        slideMap.set(prefixed, JSON.stringify(value));
+      }
+    }
+    const elementsArray = new Array$1();
+    for (const element of slide.elements) {
+      elementsArray.push([this._elementToYMap(element)]);
+    }
+    slideMap.set("elements", elementsArray);
+    return slideMap;
+  }
+  _yMapToSlide(slideMap) {
+    const slide = {};
+    for (const key of SCALAR_SLIDE_KEYS) {
+      const value = slideMap.get(key);
+      if (value !== void 0) {
+        slide[key] = value;
+      }
+    }
+    for (const [prefixed, original] of Object.entries(REVERSE_COMPLEX_SLIDE_MAP)) {
+      const value = slideMap.get(prefixed);
+      if (value !== void 0) {
+        slide[original] = JSON.parse(value);
+      }
+    }
+    const elementsArray = slideMap.get("elements");
+    const elements = [];
+    if (elementsArray) {
+      for (let i = 0; i < elementsArray.length; i++) {
+        const elemMap = elementsArray.get(i);
+        elements.push(this._yMapToElement(elemMap));
+      }
+    }
+    slide["elements"] = elements;
+    return slide;
+  }
+  _elementToYMap(element) {
+    const elemMap = new Map();
+    const record = element;
+    for (const [key, value] of Object.entries(record)) {
+      if (value === void 0) {
+        continue;
+      }
+      if (SCALAR_ELEMENT_KEYS.has(key)) {
+        elemMap.set(key, value);
+      } else if (COMPLEX_FIELD_MAP[key]) {
+        elemMap.set(COMPLEX_FIELD_MAP[key], JSON.stringify(value));
+      }
+    }
+    return elemMap;
+  }
+  _yMapToElement(elemMap) {
+    const element = {};
+    elemMap.forEach((value, key) => {
+      if (REVERSE_COMPLEX_MAP[key]) {
+        element[REVERSE_COMPLEX_MAP[key]] = JSON.parse(value);
+      } else {
+        element[key] = value;
+      }
+    });
+    return element;
+  }
+};
+
+export { ORIGIN_FILE_LOAD, PptxCodec };