pptx-viewer-mcp 1.1.0

package/dist/index.d.mts

@@ -0,0 +1,480 @@
+import { PptxData, PptxElement, PptxSlide, ShapeStyle } from 'pptx-viewer-core';
+import { Doc } from 'yjs';
+
+/**
+ * Platform-agnostic context passed to every tool function.
+ * No Electron, no RoomManager, no framework dependencies.
+ */
+interface ToolContext {
+    /** Current presentation data (parsed PptxData from pptx-viewer-core). */
+    pptxData: PptxData;
+    /** Optional: resolve external image paths to binary data. */
+    resolveImage?: (path: string) => Promise<Uint8Array>;
+    /** Optional: resolve external media paths to binary data. */
+    resolveMedia?: (path: string) => Promise<Uint8Array>;
+}
+/**
+ * Every tool function returns this.
+ * The consumer decides what to do with the mutated pptxData.
+ */
+interface ToolResult<T = unknown> {
+    /** The (potentially mutated) presentation data. */
+    pptxData: PptxData;
+    /** Tool-specific return value (e.g., slide info, element ID, search results). */
+    result: T;
+    /** Whether pptxData was modified (signals need to save). */
+    dirty: boolean;
+}
+
+/**
+ * Abstraction for Y.Doc room management.
+ * fz-electron implements this with RoomManager.
+ */
+interface CollaborationProvider {
+    /** Get an active collaboration room for a file path, or null. */
+    getRoom(filePath: string): {
+        ydoc: Doc;
+    } | null;
+    /** Get the format codec for a file path, or null. */
+    getCodec(filePath: string): {
+        hydrate(ydoc: Doc, bytes: Uint8Array, origin?: string): Promise<void>;
+        dehydrate(ydoc: Doc): Promise<Uint8Array>;
+    } | null;
+    /** Create an agent origin tag for undo isolation. */
+    agentOrigin(name: string): string;
+}
+/**
+ * Abstraction for file system access.
+ * fz-electron implements this with window.electron.files.
+ * MCP server implements this with node:fs.
+ */
+interface FileSystemProvider {
+    readFile(path: string): Promise<Uint8Array>;
+    writeFile(path: string, data: Uint8Array): Promise<void>;
+}
+/**
+ * Abstraction for updating an open file viewer.
+ * Only fz-electron implements this.
+ */
+interface ViewerProvider {
+    replaceContent(filePath: string, bytes: Uint8Array, options: {
+        markDirty: boolean;
+        mimeType?: string;
+    }): void;
+    openFile(filePath: string): Promise<void>;
+}
+/**
+ * Full execution context for running tools with collaboration support.
+ */
+interface ExecutionContext {
+    /** File system for reading/writing PPTX files. */
+    filesystem: FileSystemProvider;
+    /** Optional collaboration provider for Y.Doc routing. */
+    collaboration?: CollaborationProvider;
+    /** Optional viewer integration for live document updates. */
+    viewer?: ViewerProvider;
+    /** Agent name for collaboration origin tracking. */
+    agentName?: string;
+}
+
+/**
+ * Load PptxData from a file, checking collaboration rooms first.
+ * If a Y.Doc room is active the current in-memory state is dehydrated
+ * so that unsaved edits are included in the tool's view of the document.
+ */
+declare function loadPresentation(filePath: string, execCtx: ExecutionContext): Promise<{
+    pptxData: PptxData;
+    rawBytes: Uint8Array;
+}>;
+/**
+ * Save mutated PptxData back — routes through collaboration Y.Doc or disk.
+ */
+declare function savePresentation(filePath: string, pptxData: PptxData, rawBytes: Uint8Array, execCtx: ExecutionContext): Promise<{
+    savedToDisk: boolean;
+    routedThroughCollaboration: boolean;
+}>;
+/**
+ * Execute a pure tool function with full collaboration-aware load/save pipeline.
+ * Handles dehydrate-from-room → tool → hydrate-back-to-room routing automatically.
+ */
+declare function executeToolWithContext<T>(filePath: string, execCtx: ExecutionContext, toolFn: (ctx: ToolContext) => ToolResult<T> | Promise<ToolResult<T>>): Promise<T & {
+    savedToDisk?: boolean;
+    routedThroughCollaboration?: boolean;
+}>;
+
+interface GetSlideResult {
+    slideIndex: number;
+    slideNumber: number;
+    hidden: boolean;
+    layoutName?: string;
+    backgroundColor?: string;
+    notes: string;
+    commentCount: number;
+    elements: Record<string, unknown>[];
+}
+declare function getSlide(ctx: ToolContext, params: {
+    slideIndex: number;
+}): ToolResult<GetSlideResult>;
+interface AddSlideParams {
+    insertAfterIndex?: number;
+    backgroundColor?: string;
+}
+interface AddSlideResult {
+    newSlideIndex: number;
+    slideCount: number;
+}
+declare function addSlide(ctx: ToolContext, params: AddSlideParams): ToolResult<AddSlideResult>;
+interface DeleteSlidesParams {
+    slideIndexes: number[];
+}
+interface DeleteSlidesResult {
+    deletedCount: number;
+    slideCount: number;
+}
+declare function deleteSlides(ctx: ToolContext, params: DeleteSlidesParams): ToolResult<DeleteSlidesResult>;
+interface ReorderSlidesParams {
+    newOrder: number[];
+}
+declare function reorderSlides(ctx: ToolContext, params: ReorderSlidesParams): ToolResult<{
+    slideCount: number;
+}>;
+interface DuplicateSlideParams {
+    slideIndex: number;
+    targetIndex?: number;
+}
+declare function duplicateSlide(ctx: ToolContext, params: DuplicateSlideParams): ToolResult<{
+    newSlideIndex: number;
+    slideCount: number;
+}>;
+interface UpdateSlidePropertiesParams {
+    slideIndex: number;
+    backgroundColor?: string;
+    backgroundGradient?: string;
+    backgroundImage?: string;
+    notes?: string;
+    hidden?: boolean;
+}
+declare function updateSlideProperties(ctx: ToolContext, params: UpdateSlidePropertiesParams): ToolResult<{
+    slideIndex: number;
+}>;
+interface SetSlideTransitionParams {
+    slideIndex: number;
+    type: string;
+    durationMs?: number;
+    direction?: string;
+    advanceOnClick?: boolean;
+    advanceAfterMs?: number;
+}
+declare function setSlideTransition(ctx: ToolContext, params: SetSlideTransitionParams): ToolResult<{
+    slideIndex: number;
+    transitionType: string;
+}>;
+interface SetCanvasSizeParams {
+    width: number;
+    height: number;
+}
+declare function setCanvasSize(ctx: ToolContext, params: SetCanvasSizeParams): ToolResult<{
+    canvasWidth: number;
+    canvasHeight: number;
+}>;
+
+declare function generateElementId(): string;
+declare function generateSlideId(): string;
+/** Build a concise text representation of a slide element for tool output. */
+declare function describeElement(el: PptxElement): Record<string, unknown>;
+/** Extract text from a slide's elements for search purposes. */
+declare function extractSlideText(slide: PptxSlide): string;
+/** Validate slideIndex is within range, return error string or null. */
+declare function validateSlideIndex(slideIndex: number, slideCount: number): string | null;
+
+interface AddElementParams {
+    slideIndex: number;
+    type: 'text' | 'shape' | 'image' | 'table' | 'connector';
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    text?: string;
+    fontSize?: number;
+    fontFamily?: string;
+    fontColor?: string;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    alignment?: 'left' | 'center' | 'right' | 'justify';
+    shapeType?: string;
+    fillColor?: string;
+    strokeColor?: string;
+    strokeWidth?: number;
+    imageData?: string;
+    altText?: string;
+    rows?: number;
+    columns?: number;
+    cellData?: string[][];
+    headerRow?: boolean;
+    startArrow?: string;
+    endArrow?: string;
+    startShapeId?: string;
+    endShapeId?: string;
+}
+interface AddElementResult {
+    elementId: string;
+    slideIndex: number;
+}
+declare function addElement(ctx: ToolContext, params: AddElementParams): ToolResult<AddElementResult>;
+interface UpdateElementParams {
+    slideIndex: number;
+    elementId: string;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    rotation?: number;
+    text?: string;
+    fontSize?: number;
+    fontFamily?: string;
+    fontColor?: string;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    alignment?: 'left' | 'center' | 'right' | 'justify';
+    fillColor?: string;
+    strokeColor?: string;
+    strokeWidth?: number;
+    opacity?: number;
+    hidden?: boolean;
+    flipH?: boolean;
+    flipV?: boolean;
+}
+declare function updateElement(ctx: ToolContext, params: UpdateElementParams): ToolResult<{
+    elementId: string;
+}>;
+interface DeleteElementsParams {
+    slideIndex: number;
+    elementIds: string[];
+}
+declare function deleteElements(ctx: ToolContext, params: DeleteElementsParams): ToolResult<{
+    deletedCount: number;
+}>;
+interface ArrangeElementsParams {
+    slideIndex: number;
+    action: 'align' | 'reorderLayer';
+    elementIds?: string[];
+    alignment?: 'left' | 'right' | 'top' | 'bottom' | 'centerH' | 'centerV';
+    elementId?: string;
+    layerAction?: 'bringToFront' | 'sendToBack' | 'bringForward' | 'sendBackward';
+}
+declare function arrangeElements(ctx: ToolContext, params: ArrangeElementsParams): ToolResult<{
+    slideIndex: number;
+}>;
+interface CloneElementParams {
+    slideIndex: number;
+    elementId: string;
+    targetSlideIndexes?: number[];
+    offsetX?: number;
+    offsetY?: number;
+}
+interface CloneElementResult {
+    clonedIds: string[];
+}
+declare function cloneElement(ctx: ToolContext, params: CloneElementParams): ToolResult<CloneElementResult>;
+interface SetElementAnimationParams {
+    slideIndex: number;
+    elementId: string;
+    entrance?: string;
+    exit?: string;
+    durationMs?: number;
+    delayMs?: number;
+    order?: number;
+}
+declare function setElementAnimation(ctx: ToolContext, params: SetElementAnimationParams): ToolResult<{
+    elementId: string;
+}>;
+interface GroupElementsParams {
+    slideIndex: number;
+    elementIds: string[];
+}
+interface GroupElementsResult {
+    groupId: string;
+}
+declare function groupElements(ctx: ToolContext, params: GroupElementsParams): ToolResult<GroupElementsResult>;
+interface UngroupElementsParams {
+    slideIndex: number;
+    groupElementId: string;
+}
+interface UngroupElementsResult {
+    restoredIds: string[];
+}
+declare function ungroupElements(ctx: ToolContext, params: UngroupElementsParams): ToolResult<UngroupElementsResult>;
+interface BatchUpdateElementsParams {
+    slideIndex: number;
+    elementIds: string[];
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    rotation?: number;
+    opacity?: number;
+    hidden?: boolean;
+}
+declare function batchUpdateElements(ctx: ToolContext, params: BatchUpdateElementsParams): ToolResult<{
+    updatedCount: number;
+}>;
+
+interface UpdateTableCellsParams {
+    slideIndex: number;
+    elementId: string;
+    cells: Array<{
+        row: number;
+        col: number;
+        text: string;
+    }>;
+}
+declare function updateTableCells(ctx: ToolContext, params: UpdateTableCellsParams): ToolResult<{
+    updatedCount: number;
+}>;
+interface ManageTableStructureParams {
+    slideIndex: number;
+    elementId: string;
+    action: 'insertRow' | 'deleteRow' | 'insertColumn' | 'deleteColumn';
+    position?: number;
+    referenceIndex?: number;
+    cellTexts?: string[];
+}
+declare function manageTableStructure(ctx: ToolContext, params: ManageTableStructureParams): ToolResult<{
+    rowCount: number;
+    columnCount: number;
+}>;
+
+interface UpdateElementStyleParams {
+    slideIndex: number;
+    elementId: string;
+    fillColor?: string;
+    fillMode?: ShapeStyle['fillMode'];
+    fillGradientStops?: Array<{
+        color: string;
+        position: number;
+        opacity?: number;
+    }>;
+    fillGradientAngle?: number;
+    fillGradientType?: 'linear' | 'radial';
+    fillOpacity?: number;
+    strokeColor?: string;
+    strokeWidth?: number;
+    strokeDash?: ShapeStyle['strokeDash'];
+    strokeOpacity?: number;
+    shadowColor?: string;
+    shadowBlur?: number;
+    shadowOffsetX?: number;
+    shadowOffsetY?: number;
+    shadowOpacity?: number;
+    glowColor?: string;
+    glowRadius?: number;
+    glowOpacity?: number;
+    softEdgeRadius?: number;
+    cropLeft?: number;
+    cropTop?: number;
+    cropRight?: number;
+    cropBottom?: number;
+    brightness?: number;
+    contrast?: number;
+    grayscale?: boolean;
+    altText?: string;
+}
+declare function updateElementStyle(ctx: ToolContext, params: UpdateElementStyleParams): ToolResult<{
+    elementId: string;
+}>;
+interface AccessibilityIssue {
+    slideIndex: number;
+    elementId?: string;
+    severity: 'error' | 'warning' | 'info';
+    message: string;
+}
+interface AccessibilityCheckResult {
+    slideCount: number;
+    totalIssues: number;
+    errorCount: number;
+    warningCount: number;
+    infoCount: number;
+    issues: AccessibilityIssue[];
+}
+declare function runAccessibilityCheck(ctx: ToolContext): ToolResult<AccessibilityCheckResult>;
+
+interface FindTextParams {
+    query: string;
+    useRegex?: boolean;
+    caseSensitive?: boolean;
+    slideIndexes?: number[];
+}
+interface TextMatch {
+    slideIndex: number;
+    elementId: string;
+    elementType: string;
+    matchedText: string;
+    context: string;
+}
+interface FindTextResult {
+    query: string;
+    matchCount: number;
+    matches: TextMatch[];
+}
+declare function findText(ctx: ToolContext, params: FindTextParams): ToolResult<FindTextResult>;
+interface ReplaceTextParams {
+    query: string;
+    replacement: string;
+    useRegex?: boolean;
+    caseSensitive?: boolean;
+    slideIndexes?: number[];
+}
+interface ReplaceTextResult {
+    query: string;
+    replacement: string;
+    replacementCount: number;
+}
+declare function replaceText(ctx: ToolContext, params: ReplaceTextParams): ToolResult<ReplaceTextResult>;
+interface ManageCommentsParams {
+    action: 'list' | 'add' | 'delete' | 'resolve';
+    slideIndex?: number;
+    text?: string;
+    author?: string;
+    commentId?: string;
+    resolved?: boolean;
+    includeResolved?: boolean;
+}
+interface CommentInfo {
+    id: string;
+    slideIndex: number;
+    text: string;
+    author?: string;
+    createdAt?: string;
+    resolved?: boolean;
+}
+interface ManageCommentsResult {
+    action: string;
+    comments?: CommentInfo[];
+    commentId?: string;
+    count?: number;
+}
+declare function manageComments(ctx: ToolContext, params: ManageCommentsParams): ToolResult<ManageCommentsResult>;
+
+interface ConvertToMarkdownParams {
+    outputDir?: string;
+    mediaFolderName?: string;
+    includeMetadata?: boolean;
+    slideRange?: {
+        start?: number;
+        end?: number;
+    };
+    includeSpeakerNotes?: boolean;
+    semanticMode?: boolean;
+    sourceName?: string;
+}
+interface ConvertToMarkdownResult {
+    markdown: string;
+    slidesConverted: number;
+    totalSlides: number;
+    imagesExtracted: number;
+}
+declare function convertToMarkdown(ctx: ToolContext, params: ConvertToMarkdownParams): Promise<ToolResult<ConvertToMarkdownResult>>;
+
+export { type AccessibilityCheckResult, type AccessibilityIssue, type AddElementParams, type AddElementResult, type AddSlideParams, type AddSlideResult, type ArrangeElementsParams, type BatchUpdateElementsParams, type CloneElementParams, type CloneElementResult, type CollaborationProvider, type CommentInfo, type ConvertToMarkdownParams, type ConvertToMarkdownResult, type DeleteElementsParams, type DeleteSlidesParams, type DeleteSlidesResult, type DuplicateSlideParams, type ExecutionContext, type FileSystemProvider, type FindTextParams, type FindTextResult, type GetSlideResult, type GroupElementsParams, type GroupElementsResult, type ManageCommentsParams, type ManageCommentsResult, type ManageTableStructureParams, type ReorderSlidesParams, type ReplaceTextParams, type ReplaceTextResult, type SetCanvasSizeParams, type SetElementAnimationParams, type SetSlideTransitionParams, type TextMatch, type ToolContext, type ToolResult, type UngroupElementsParams, type UngroupElementsResult, type UpdateElementParams, type UpdateElementStyleParams, type UpdateSlidePropertiesParams, type UpdateTableCellsParams, type ViewerProvider, addElement, addSlide, arrangeElements, batchUpdateElements, cloneElement, convertToMarkdown, deleteElements, deleteSlides, describeElement, duplicateSlide, executeToolWithContext, extractSlideText, findText, generateElementId, generateSlideId, getSlide, groupElements, loadPresentation, manageComments, manageTableStructure, reorderSlides, replaceText, runAccessibilityCheck, savePresentation, setCanvasSize, setElementAnimation, setSlideTransition, ungroupElements, updateElement, updateElementStyle, updateSlideProperties, updateTableCells, validateSlideIndex };