Convert a .docx/.xlsx/.pptx file to pdf/html/csv.

Dispatches to the format-specific exporter based on the source file's extension and the requested target_format. When output is omitted, the output is written next to the source with the new extension (VAL-GEN-024).

Args: path: Path to an existing Office file. target_format: One of "pdf", "html", "csv". The match is case-insensitive and a leading dot is tolerated. output: Optional target path for the converted file. When None (default), a sibling of the input is used. Relative paths are resolved against folder (or the default folder). folder: Optional base folder for relative paths.

Returns: {"output_path": "<absolute path>", "format": <target>} where format is the lower-cased, dot-stripped target format (e.g. "pdf").

Raises: OfficeMCPError: ERR_INVALID_PARAMS for unknown target_format, ERR_FILE_NOT_FOUND if the source is missing, ERR_UNSUPPORTED_FMT for an unsupported (source, target) combination (e.g. .docx → .csv, or any non-Office source), or any error propagated from :mod:office_mcp.exporters (ERR_LIBREOFFICE_MISSING, ERR_EXPORT_FAILED).

Add a chart to a sheet, anchored at target_cell.

Supported chart_type values: "bar", "line", "pie", "area", "scatter". Any other value raises :class:OfficeMCPError with ERR_INVALID_PARAMS (VAL-EXCEL-056) and the workbook is not modified.

The chart's data is read from data_range (e.g. "A1:B5"); the first column is treated as categories and subsequent columns as series. The chart is anchored at target_cell (e.g. "D2") so its top-left corner coincides with that cell (VAL-EXCEL-052).

Args: path: Path to an existing .xlsx. sheet: Name of the sheet that will own the chart. chart_type: One of "bar", "line", "pie", "area", "scatter". data_range: A range reference like "A1:B5". target_cell: A single cell reference like "D2". The chart's top-left anchor is set to this cell. title: Optional chart title. When supplied, it is set via openpyxl's title API and survives a reload. folder: Optional base folder for relative paths.

Returns: {"ok": True}.

Raises: OfficeMCPError: ERR_FILE_NOT_FOUND if the file is missing, ERR_SHEET_NOT_FOUND for an unknown sheet, ERR_INVALID_PARAMS for an unknown chart_type or malformed data_range / target_cell, ERR_CELL_PARSE for a malformed range, ERR_UNSUPPORTED_FMT for non-.xlsx extensions.

Append a new sheet to the workbook.

Args: path: Path to an existing .xlsx. name: Name of the new sheet. Must be non-empty and free of Excel-forbidden characters (: / \ ? * [ ]). folder: Optional base folder for relative paths.

Returns: {"index": <n>} where <n> is the position of the new sheet in wb.sheetnames (0-based).

Raises: OfficeMCPError: ERR_FILE_NOT_FOUND if the file is missing, ERR_INVALID_PARAMS for a duplicate or malformed name, ERR_UNSUPPORTED_FMT for non-.xlsx extensions.

Create a new .xlsx file at path.

Args: path: Target .xlsx path. May be absolute or relative to folder (or to the default folder when folder is None). sheet_name: Optional name for the initial sheet. When None (the default), the openpyxl default "Sheet1" is used. folder: Optional base folder for relative paths.

Returns: {"path": "<absolute path>"}.

Raises: OfficeMCPError: ERR_INVALID_PARAMS if path is empty or a file already exists at the target (or the requested sheet name is malformed). ERR_UNSUPPORTED_FMT if path does not end in .xlsx.

Remove a sheet from the workbook.

Refuses to delete the last remaining sheet (VAL-EXCEL-036 / VAL-EXCEL-037): the workbook must always have at least one sheet.

Args: path: Path to an existing .xlsx. name: Name of the sheet to delete. folder: Optional base folder for relative paths.

Returns: {"ok": True}.

Raises: OfficeMCPError: ERR_FILE_NOT_FOUND if the file is missing, ERR_SHEET_NOT_FOUND for an unknown sheet, ERR_INVALID_PARAMS when the target is the only remaining sheet, ERR_UNSUPPORTED_FMT for non-.xlsx extensions.

Export a sheet to CSV via :mod:openpyxl and the stdlib :mod:csv.

Delegates to :func:office_mcp.exporters.export_to_csv. The output is written as UTF-8 (without a BOM) and uses the standard Excel-friendly CSV dialect.

Args: path: Path to an existing .xlsx file. output: Target path for the produced .csv. The parent directory is created if it does not exist. If a relative path is given, it is resolved against folder (or the default folder). sheet: Optional sheet name. When None (the default), the workbook's first sheet is exported. folder: Optional base folder for relative paths.

Returns: {"output_path": "<absolute path of the produced CSV>"}.

Raises: OfficeMCPError: ERR_FILE_NOT_FOUND if the source is missing, ERR_UNSUPPORTED_FMT for non-.xlsx sources, ERR_SHEET_NOT_FOUND for an unknown sheet.

Convert a .xlsx file to HTML via LibreOffice headless.

Delegates to :func:office_mcp.exporters.export_to_html. Unlike the Word variant this path always goes through LibreOffice (openpyxl does not produce standalone HTML).

Args: path: Path to an existing .xlsx file. output: Target path for the produced HTML. The parent directory is created if it does not exist. If a relative path is given, it is resolved against folder (or the default folder). folder: Optional base folder for relative paths.

Returns: {"output_path": "<absolute path of the produced HTML>"}.

Raises: OfficeMCPError: ERR_FILE_NOT_FOUND if the source is missing, ERR_UNSUPPORTED_FMT for non-.xlsx sources, ERR_LIBREOFFICE_MISSING when soffice is not on PATH, ERR_EXPORT_FAILED for any other failure.

Convert a .xlsx file to PDF via LibreOffice headless.

Delegates to :func:office_mcp.exporters.export_to_pdf. A unique -env:UserInstallation is used per call so multiple exports can run concurrently.

Args: path: Path to an existing .xlsx file. output: Target path for the produced PDF. The parent directory is created if it does not exist. If a relative path is given, it is resolved against folder (or the default folder). folder: Optional base folder for relative paths.

Returns: {"output_path": "<absolute path of the produced PDF>"}.

Raises: OfficeMCPError: ERR_FILE_NOT_FOUND if the source is missing, ERR_UNSUPPORTED_FMT for non-.xlsx sources, ERR_LIBREOFFICE_MISSING when soffice is not on PATH, ERR_EXPORT_FAILED for any other failure.

Apply font, fill, border, alignment, and number-format to a range.

Each formatting argument is None by default and is treated as "do not change". When every formatting argument is None, the call is a true no-op: the file is not re-saved, so its SHA256 and mtime are preserved (VAL-EXCEL-049).

Args: path: Path to an existing .xlsx. sheet: Name of the sheet to format. cell_range: A cell reference ("A1") or a range ("A1:C3"). Column letters may be upper or lower case. bold: True / False to set font.bold, or None to leave it alone. italic: Same semantics as bold for font.italic. font_name: A font family name (e.g. "Arial"). font_size: Point size (e.g. 14). font_color: Hex RGB string ("FF0000"). fill_color: Hex RGB string for the cell background. border: Either a single style name applied to all four sides ("thin", "medium", "thick", "dashed", "dotted", "double", "hair") or a dict mapping "left" / "right" / "top" / "bottom" to a style name. alignment: "left" / "center" / "right" / "justify" / "general" for Alignment.horizontal. number_format: An Excel number format code (e.g. "0.00%", "#,##0.00", "yyyy-mm-dd"). folder: Optional base folder for relative paths.

Returns: {"ok": True}.

Raises: OfficeMCPError: ERR_FILE_NOT_FOUND if the file is missing, ERR_SHEET_NOT_FOUND for an unknown sheet, ERR_CELL_PARSE for a malformed range, ERR_INVALID_PARAMS for an unknown border style or alignment, ERR_UNSUPPORTED_FMT for non-.xlsx extensions.

Return a summary of the workbook's sheets and sizes.

The returned dict contains:

• path — absolute path of the file on disk.

• sheets — list of one dict per sheet, in insertion order. Each entry has name (str), index (int, 0-based), rows (int, openpyxl's max_row), and cols (int, openpyxl's max_column).

Args: path: Path to an existing .xlsx. folder: Optional base folder for relative paths.

Raises: OfficeMCPError: ERR_FILE_NOT_FOUND if the file is missing, ERR_UNSUPPORTED_FMT for non-.xlsx extensions.

Return one dict per sheet in the workbook (insertion order).

Each entry is identical to those in :func:excel_get_info['sheets'].

Args: path: Path to an existing .xlsx. folder: Optional base folder for relative paths.

Raises: OfficeMCPError: ERR_FILE_NOT_FOUND if the file is missing, ERR_UNSUPPORTED_FMT for non-.xlsx extensions.

Read cell values from a sheet, optionally limited to a range.

Args: path: Path to an existing .xlsx. sheet: Name of the sheet to read. range: Optional cell or range reference. Accepts:

    * ``None`` — read the entire used range
      (``ws.max_row`` × ``ws.max_column``).
    * ``"A1"`` — read a single cell; the result is a 1x1 list
      ``[[value]]``.
    * ``"A1:C3"`` — read a rectangular range. Reversed ranges
      (``"C3:A1"``) are rejected.

    Column letters may be lower-case or upper-case.
folder: Optional base folder for relative paths.

Returns: A 2D list of values. Empty cells (None) are normalised to the empty string "" so the result is JSON-friendly.

Raises: OfficeMCPError: ERR_FILE_NOT_FOUND if the file is missing, ERR_SHEET_NOT_FOUND if sheet is not in the workbook, ERR_CELL_PARSE for malformed range, ERR_UNSUPPORTED_FMT for non-.xlsx extensions.

Rename a sheet in the workbook.

Cell contents are preserved across the rename (VAL-EXCEL-042). Renaming a sheet to its own name is a no-op (the file is still saved, but the sheet names are unchanged — VAL-EXCEL-041).

Args: path: Path to an existing .xlsx. old_name: Current name of the sheet to rename. new_name: Desired new name. Must be non-empty and free of Excel-forbidden characters. folder: Optional base folder for relative paths.

Returns: {"ok": True}.

Raises: OfficeMCPError: ERR_FILE_NOT_FOUND if the file is missing, ERR_SHEET_NOT_FOUND for an unknown old_name, ERR_INVALID_PARAMS when new_name is empty, contains forbidden characters, or already exists as another sheet, ERR_UNSUPPORTED_FMT for non-.xlsx extensions.

Write a single value to one cell.

Strings starting with = are persisted as formulas (VAL-EXCEL-022). Other types (int, float, bool, None) are written verbatim via :meth:openpyxl.cell.Cell.value.

Args: path: Path to an existing .xlsx. sheet: Name of the sheet. cell: A single cell reference like "A1". value: Value to write. folder: Optional base folder for relative paths.

Returns: {"ok": True}.

Raises: OfficeMCPError: ERR_FILE_NOT_FOUND if the file is missing, ERR_SHEET_NOT_FOUND for an unknown sheet, ERR_CELL_PARSE for a malformed cell, ERR_UNSUPPORTED_FMT for non-.xlsx extensions.

Write a 2D list of values starting at start_cell.

The data is interpreted in row-major order: data[0][0] goes to start_cell, data[0][1] to the cell one column to the right, data[1][0] to the cell one row below, and so on. Writing extends the sheet's used range as needed (VAL-EXCEL-027).

Args: path: Path to an existing .xlsx. sheet: Name of the sheet. start_cell: Top-left cell of the write region (e.g. "A1"). data: 2D list of values. The empty list [] is accepted and is a no-op (the file is still saved; the workbook remains valid). folder: Optional base folder for relative paths.

Returns: {"ok": True}.

Raises: OfficeMCPError: ERR_FILE_NOT_FOUND if the file is missing, ERR_SHEET_NOT_FOUND for an unknown sheet, ERR_CELL_PARSE for a malformed start_cell, ERR_INVALID_PARAMS if data is not a list, ERR_UNSUPPORTED_FMT for non-.xlsx extensions.

Return metadata for a single Office file.

Detects the format by extension and dispatches to the format-specific *_get_info tool. The returned dict is a superset of the underlying tool's dict, augmented with type ("word" / "excel" / "pptx") and size_bytes.

Args: path: Path to an existing Office file (abs or relative to folder/default folder). folder: Optional base folder for relative paths.

Returns: A dict with:

* ``type`` — one of ``"word"``, ``"excel"``, ``"pptx"``.
* ``size_bytes`` — file size in bytes.
* Format-specific fields: for ``.docx`` →
  ``paragraphs``, ``sections``, ``tables``, ``images``,
  ``properties``; for ``.xlsx`` → ``sheets`` (list),
  ``sheet_count``, ``sheet_names``; for ``.pptx`` →
  ``slide_count``, ``layouts``, ``dimensions_inches`` (with
  ``width_inches`` / ``height_inches``).

Raises: OfficeMCPError: ERR_FILE_NOT_FOUND if the file is missing (VAL-GEN-010), ERR_UNSUPPORTED_FMT if the extension is not one of .docx / .xlsx / .pptx.

List all Office files in a folder (non-recursive).

Scans the immediate children of folder and returns one entry per file with extension .docx/.xlsx/.pptx. Non-Office files (and subdirectories) are filtered out. The scan does not descend into subdirectories.

Args: folder: Folder to scan. When None (default), the default folder from :func:office_mcp.config.get_default_folder is used. Relative paths are joined with the default folder.

Returns: A list of dicts, each with:

* ``path`` — absolute, canonical path to the file.
* ``name`` — file basename (e.g. ``"report.docx"``).
* ``type`` — one of ``"word"``, ``"excel"``, ``"pptx"``.
* ``size_bytes`` — file size on disk (positive int).
* ``modified`` — ISO-8601 timestamp of last modification
  (``datetime.fromisoformat``-parseable, with timezone).

An empty folder returns ``[]`` (``VAL-GEN-002``).

Raises: OfficeMCPError: ERR_INVALID_PARAMS if folder exists but is not a directory.

Add a chart to a slide.

The data argument must follow the structure documented in :func:_build_chart_data: a dict with "categories" (list of x-axis labels) and "series" (list of {"name", "values"} dicts).

Args: path: Path to an existing .pptx. chart_type: One of column, bar, line, pie, etc. — see :data:_CHART_TYPE_MAP. (VAL-PPTX-051, VAL-PPTX-052.) data: Chart data structure with categories and series keys (VAL-PPTX-051). x: Left edge in inches. y: Top edge in inches. w: Width in inches. h: Height in inches. slide: 0-based slide index (VAL-PPTX-055). folder: Optional base folder for relative paths.

Returns: {"shape_index": <int>} — 0-based index of the new chart within the slide's shape list.

Raises: OfficeMCPError: ERR_INVALID_PARAMS for unknown chart_type (VAL-PPTX-053), empty series (VAL-PPTX-054), out-of-range slide (VAL-PPTX-055), or non-numeric geometry; ERR_FILE_NOT_FOUND if the file is missing; ERR_UNSUPPORTED_FMT for non-.pptx extensions.

Add an image to a slide at the given inch coordinates.

The w / h arguments control the rendered size:

• Both given — the picture is stretched to exactly those dimensions (VAL-PPTX-036).

• Only w given — h is computed from the image's intrinsic aspect ratio (VAL-PPTX-038). Aspect ratio preserved within 1% tolerance.

• Only h given — w is computed from the image's intrinsic aspect ratio (VAL-PPTX-039).

• Neither given — the picture is rendered at its natural pixel size at 96 DPI (VAL-PPTX-037).

Args: path: Path to an existing .pptx. image_path: Path to the image to embed (any format python-pptx can read: PNG, JPEG, GIF, BMP, TIFF). x: Left edge in inches. y: Top edge in inches. w: Optional width in inches. None = compute from aspect ratio (when h is given) or use natural size. h: Optional height in inches. None = compute from aspect ratio (when w is given) or use natural size. slide: 0-based slide index. folder: Optional base folder for relative paths. Used for both the deck and the image path.

Returns: {"shape_index": <int>} — 0-based index of the new picture within the slide's shape list.

Raises: OfficeMCPError: ERR_FILE_NOT_FOUND if either the deck or the image file is missing (VAL-PPTX-040); ERR_INVALID_PARAMS for out-of-range slide (VAL-PPTX-041) or non-numeric geometry; ERR_UNSUPPORTED_FMT for non-.pptx extensions.

Add a shape (rectangle, oval, etc.) to a slide.

shape_type is one of the case-insensitive names mapped by :data:_SHAPE_TYPE_MAP — the supported set covers the most common MSO_SHAPE members (VAL-PPTX-042 for rectangle, VAL-PPTX-043 for oval and rounded rectangle). An unknown type returns ERR_INVALID_PARAMS and the deck is left unchanged (VAL-PPTX-044).

Args: path: Path to an existing .pptx. shape_type: Shape type (e.g. "rectangle", "oval", "rounded_rectangle"). See :data:_SHAPE_TYPE_MAP. x: Left edge in inches. y: Top edge in inches. w: Width in inches. h: Height in inches. slide: 0-based slide index (VAL-PPTX-045). folder: Optional base folder for relative paths. text: Optional text to put inside the shape's text frame.

Returns: {"shape_index": <int>} — 0-based index of the new shape within the slide's shape list.

Raises: OfficeMCPError: ERR_INVALID_PARAMS for an unknown shape type, out-of-range slide, or non-numeric geometry; ERR_FILE_NOT_FOUND if the file is missing; ERR_UNSUPPORTED_FMT for non-.pptx extensions.

Append a new slide to the deck.

The slide is always appended to the end (VAL-PPTX-018 — the returned index equals the previous slide count). When title is given, the slide's title placeholder is populated (VAL-PPTX-021).

Args: path: Path to an existing .pptx. layout_index: 0-based index into prs.slide_layouts. The default 1 is the "Title and Content" layout in python-pptx's default template. title: Optional title text. When None the title placeholder is left empty. folder: Optional base folder for relative paths.

Returns: {"index": <int>} — the 0-based index of the new slide.

Raises: OfficeMCPError: ERR_INVALID_PARAMS for a non-int or out-of-range layout_index (the deck is not modified in this case — VAL-PPTX-020), ERR_FILE_NOT_FOUND if the file is missing, ERR_UNSUPPORTED_FMT for non-.pptx extensions.

Add a table to a slide.

When data is None the table is created with every cell empty (VAL-PPTX-047). When data is shorter than rows x cols the missing cells are padded with empty strings (VAL-PPTX-048). All cell values are coerced to str before being written.

Args: path: Path to an existing .pptx. rows: Number of rows (must be > 0; VAL-PPTX-050). cols: Number of columns (must be > 0). x: Left edge in inches. y: Top edge in inches. w: Width in inches. h: Height in inches. slide: 0-based slide index (VAL-PPTX-049). folder: Optional base folder for relative paths. data: Optional 2D list of cell values, row-major.

Returns: {"shape_index": <int>} — 0-based index of the new table within the slide's shape list.

Raises: OfficeMCPError: ERR_INVALID_PARAMS for non-positive rows / cols (VAL-PPTX-050), out-of-range slide (VAL-PPTX-049), or non-numeric geometry; ERR_FILE_NOT_FOUND if the file is missing; ERR_UNSUPPORTED_FMT for non-.pptx extensions.

Add a text box with optional font properties to a slide.

The text box is appended to the slide's shape list and its 0-based index within that slide is returned (VAL-PPTX-031). When font_size / bold / italic / font_name / color are given, they are applied to the text box's first run (VAL-PPTX-032); when any of them is None the corresponding attribute is left at the layout / default value.

Args: path: Path to an existing .pptx. text: Text to put inside the text box. x: Left edge in inches (e.g. 1.0). y: Top edge in inches (e.g. 2.0). w: Width in inches (e.g. 3.0). h: Height in inches (e.g. 0.5). slide: 0-based slide index (VAL-PPTX-034). folder: Optional base folder for relative paths. font_size: Optional font size in points (VAL-PPTX-032). bold: Optional bold flag (VAL-PPTX-032). italic: Optional italic flag. font_name: Optional font name (e.g. "Arial"). color: Optional hex color string ("FF0000").

Returns: {"shape_index": <int>} — 0-based index of the new text box within the slide's shape list.

Raises: OfficeMCPError: ERR_INVALID_PARAMS for non-numeric or out-of-range geometry, out-of-range slide, or invalid color; ERR_FILE_NOT_FOUND if the file is missing; ERR_UNSUPPORTED_FMT for non-.pptx extensions.

Create a new .pptx file at path, optionally with a title slide.

Args: path: Target .pptx path. May be absolute or relative to folder (or to the default folder when folder is None). title: Optional text for the first slide's title placeholder. When None (the default), the file is created with no slides at all (VAL-PPTX-002). When a non-empty title is given, a single slide is appended using the "Title Slide" layout (index 0) and the title is written into its title placeholder (VAL-PPTX-001). folder: Optional base folder for relative paths.

Returns: {"path": "<absolute path>"}.

Raises: OfficeMCPError: ERR_INVALID_PARAMS if path is empty or a file already exists at the target, ERR_UNSUPPORTED_FMT if path does not end in .pptx.

Remove a slide from the deck.

Refuses to delete the last remaining slide (VAL-PPTX-024): the deck must always have at least one slide. After deletion the remaining slides keep their relative order, but indices past index shift down by one (VAL-PPTX-023 / -026).

Args: path: Path to an existing .pptx. index: 0-based slide index. folder: Optional base folder for relative paths.

Returns: {"ok": True}.

Raises: OfficeMCPError: ERR_INVALID_PARAMS for a non-int or out-of-range index, or when the deck has only one slide; ERR_FILE_NOT_FOUND if the file is missing; ERR_UNSUPPORTED_FMT for non-.pptx extensions.

Convert a .pptx file to HTML via LibreOffice headless.

Delegates to :func:office_mcp.exporters.export_to_html. Unlike .docx (which uses mammoth), .pptx always requires LibreOffice (VAL-PPTX-062).

Args: path: Path to an existing .pptx. output: Target path for the produced HTML. The parent directory is created if it does not exist. folder: Optional base folder for relative paths.

Returns: {"output_path": "<absolute path of the produced HTML>"}.

Raises: OfficeMCPError: ERR_FILE_NOT_FOUND if the source is missing (VAL-PPTX-063); ERR_UNSUPPORTED_FMT for non-.pptx sources (VAL-PPTX-064); ERR_LIBREOFFICE_MISSING when soffice is not on PATH (VAL-PPTX-062); ERR_EXPORT_FAILED for any other failure.

Convert a .pptx file to PDF via LibreOffice headless.

Delegates to :func:office_mcp.exporters.export_to_pdf. A unique -env:UserInstallation is used per call so multiple exports can run concurrently (VAL-WORD-079 pattern).

Args: path: Path to an existing .pptx. output: Target path for the produced PDF. The parent directory is created if it does not exist (VAL-PPTX-057). folder: Optional base folder for relative paths.

Returns: {"output_path": "<absolute path of the produced PDF>"}.

Raises: OfficeMCPError: ERR_FILE_NOT_FOUND if the source is missing (VAL-PPTX-059); ERR_UNSUPPORTED_FMT for non-.pptx sources (VAL-PPTX-060); ERR_LIBREOFFICE_MISSING when soffice is not on PATH (VAL-PPTX-058); ERR_EXPORT_FAILED for any other failure.

Return a summary of the presentation's structure and dimensions.

The returned dict contains:

• path — absolute path of the file on disk.

• slide_count — number of slides (0 is valid; VAL-PPTX-009).

• layouts — list of layout names available in the deck's slide master (always non-empty; VAL-PPTX-006 / -009).

• dimensions — {"width_inches": <float>, "height_inches": <float>}. The default widescreen template is 13.333 × 7.5 inches; the default Presentation() template is 10.0 × 7.5 inches.

Args: path: Path to an existing .pptx. folder: Optional base folder for relative paths.

Raises: OfficeMCPError: ERR_FILE_NOT_FOUND if the file is missing, ERR_UNSUPPORTED_FMT for non-.pptx extensions.

Return one dict per slide in insertion order.

Each entry has the following keys (VAL-PPTX-010):

• index — 0-based slide index.

• layout — name of the slide's layout (e.g. "Title Slide", "Title and Content").

• title — text of the slide's title placeholder, or "" when the layout has no title placeholder.

• shape_count — number of shapes on the slide (placeholders

  • pictures + text boxes + ...).

An empty deck returns [] (VAL-PPTX-011).

Args: path: Path to an existing .pptx. folder: Optional base folder for relative paths.

Raises: OfficeMCPError: ERR_FILE_NOT_FOUND if the file is missing, ERR_UNSUPPORTED_FMT for non-.pptx extensions.

Return the slide's title, layout, and shape list.

Args: path: Path to an existing .pptx. index: 0-based slide index. folder: Optional base folder for relative paths.

Returns: {"index": <int>, "layout": <str>, "title": <str>, "shapes": [<shape_dict>, ...]}.

Each ``shape_dict`` has ``type`` (shape class name),
``shape_type`` (the numeric ``MSO_SHAPE_TYPE`` or ``None``),
``name`` (auto-generated name), and ``text`` (text-frame
text, or ``""`` for shape types without text).

Raises: OfficeMCPError: ERR_INVALID_PARAMS for a non-int or out-of-range index, ERR_FILE_NOT_FOUND if the file is missing, ERR_UNSUPPORTED_FMT for non-.pptx extensions.

Move a slide from one position to another.

This is a true move: the slide at from_index is removed first, then inserted at to_index in the resulting sequence (VAL-PPTX-027). So moving slide 0 to position 2 in a 3-slide deck [A, B, C] yields [B, C, A], not the swap result [C, B, A].

Reordering a slide to its own index (from_index == to_index) is a no-op that still returns {"ok": True} (VAL-PPTX-028).

Args: path: Path to an existing .pptx. from_index: 0-based index of the slide to move. to_index: 0-based destination index. Must satisfy 0 <= to_index < slide_count (after the slide is removed from from_index). folder: Optional base folder for relative paths.

Returns: {"ok": True}.

Raises: OfficeMCPError: ERR_INVALID_PARAMS for a non-int or out-of-range from_index / to_index, in which case the deck is left unchanged (VAL-PPTX-029); ERR_FILE_NOT_FOUND if the file is missing; ERR_UNSUPPORTED_FMT for non-.pptx extensions.

Search for a substring across the body of an Office file.

The location format depends on the source file's extension:

• .docx → "paragraph:N" (0-based body paragraph index)

• .xlsx → "cell:<coord>" (e.g. "cell:B3")

• .pptx → "slide:N:shape:M" (0-based slide + 0-based shape index in slide.shapes)

Each match entry has a location and a context field. The context is a window of up to ~30 characters on each side of the match in the original text (case preserved).

Args: path: Path to the file to search. query: Substring to look for. Must be a non-empty string. case_sensitive: When True (default), the match is exact; when False, matches are case-insensitive. folder: Optional base folder for relative paths.

Returns: A list of match dicts. Empty when there are no matches (VAL-GEN-016).

Raises: OfficeMCPError: ERR_INVALID_PARAMS if query is not a string or is empty, ERR_FILE_NOT_FOUND if the file is missing, ERR_UNSUPPORTED_FMT for non-Office files.

Set the text of a section's footer.

By default, only the first section's footer is updated; later sections keep their own footers (VAL-WORD-062). Pass an explicit section_index to target a different section.

Args: path: Path to an existing .docx. text: New footer text. An empty string clears the first paragraph (VAL-WORD-061). section_index: Zero-based section index (default 0). folder: Optional base folder for relative paths.

Returns: {"ok": True}.

Raises: OfficeMCPError: ERR_INVALID_PARAMS for a non-int or out-of-range section_index or a non-string text, ERR_FILE_NOT_FOUND if the file is missing, ERR_UNSUPPORTED_FMT for non-.docx extensions.

Set the text of a section's header.

By default, only the first section's header is updated; later sections keep their own headers (VAL-WORD-058). Pass an explicit section_index to target a different section.

Args: path: Path to an existing .docx. text: New header text. An empty string clears the first paragraph (VAL-WORD-057). section_index: Zero-based section index (default 0). folder: Optional base folder for relative paths.

Returns: {"ok": True}.

Raises: OfficeMCPError: ERR_INVALID_PARAMS for a non-int or out-of-range section_index or a non-string text, ERR_FILE_NOT_FOUND if the file is missing, ERR_UNSUPPORTED_FMT for non-.docx extensions.

Append a heading paragraph at the given level (1..9).

Args: path: Path to an existing .docx. text: Heading text. level: Heading level (1 = Heading 1, ..., 9 = Heading 9). Out-of-range values are rejected with ERR_INVALID_PARAMS. folder: Optional base folder for relative paths.

Returns: {"index": <n>} for the new heading.

Raises: OfficeMCPError: ERR_INVALID_PARAMS for an out-of-range level or a non-int level, ERR_FILE_NOT_FOUND if the file is missing, ERR_UNSUPPORTED_FMT for non- .docx extensions.

Embed an image in the document body.

When width_inches is provided, the image is scaled to that width and the height is auto-computed from the image's intrinsic aspect ratio (VAL-WORD-050 / VAL-WORD-078). When omitted, the image is embedded at its native pixel size.

Args: path: Path to an existing .docx. image_path: Path to the image file (PNG / JPEG / GIF / etc.). width_inches: Optional target width in inches (must be positive). When None the image is embedded at its native size. folder: Optional base folder for the path argument (does not apply to image_path, which is always resolved absolutely or relative to the caller's CWD).

Returns: {"index": <n>} where <n> is the index of the new inline shape in doc.inline_shapes.

Raises: OfficeMCPError: ERR_FILE_NOT_FOUND if either path is missing, ERR_INVALID_PARAMS for an unsupported image format or a non-positive width_inches, ERR_UNSUPPORTED_FMT for non-.docx extensions.

Append a paragraph to the body of the document.

Args: path: Path to an existing .docx. text: Text for the new paragraph. An empty string is accepted and produces an empty paragraph. style: Optional built-in style name (e.g. "Intense Quote"). folder: Optional base folder for relative paths.

Returns: {"index": <n>} where <n> is the index of the newly appended paragraph.

Raises: OfficeMCPError: ERR_FILE_NOT_FOUND if the file is missing, ERR_INVALID_PARAMS for bad text type or unknown style, ERR_UNSUPPORTED_FMT for non-.docx extensions.

Append a table to the body of the document.

Args: path: Path to an existing .docx. rows: Number of rows (must be a positive int). cols: Number of columns (must be a positive int). data: Optional 2D list of strings to populate the cells. The list is interpreted in row-major order; shorter rows are padded with empty strings and longer rows are truncated. style: Optional built-in table style name (e.g. "Table Grid" or "Light Grid Accent 1"). folder: Optional base folder for relative paths.

Returns: {"index": <n>} where <n> is the index of the new table in doc.tables.

Raises: OfficeMCPError: ERR_INVALID_PARAMS for non-positive rows/cols, unknown style, or a non-list data argument. ERR_FILE_NOT_FOUND if the file is missing, ERR_UNSUPPORTED_FMT for non-.docx extensions.

Create a new .docx file at path with an optional title paragraph.

Args: path: Target .docx path. May be absolute or relative to folder (or to the default folder when folder is None). title: Optional text for the first paragraph. When None the document is created with a single empty paragraph (the python-docx default). folder: Optional base folder for relative paths.

Returns: {"path": "<absolute path>"} on success.

Raises: OfficeMCPError: ERR_INVALID_PARAMS if path is empty or a file already exists at the target. ERR_UNSUPPORTED_FMT if path does not end in .docx.

Convert a .docx file to HTML via :mod:mammoth.

Delegates to :func:office_mcp.exporters.export_to_html. The .docx path uses mammoth only (no LibreOffice dependency — VAL-WORD-072).

Args: path: Path to an existing .docx file. output: Target path for the produced HTML. The parent directory is created if it does not exist. folder: Optional base folder for relative paths.

Returns: {"output_path": "<absolute path of the produced HTML>"}.

Raises: OfficeMCPError: ERR_FILE_NOT_FOUND if the source is missing, ERR_UNSUPPORTED_FMT for non-.docx sources, ERR_EXPORT_FAILED for any other failure.

Convert a .docx file to PDF via LibreOffice headless.

Delegates to :func:office_mcp.exporters.export_to_pdf. A unique -env:UserInstallation is used per call so multiple exports can run concurrently (VAL-WORD-079).

Args: path: Path to an existing .docx file. output: Target path for the produced PDF. The parent directory is created if it does not exist. If a relative path is given, it is resolved against folder (or the default folder). folder: Optional base folder for relative paths.

Returns: {"output_path": "<absolute path of the produced PDF>"}.

Raises: OfficeMCPError: ERR_FILE_NOT_FOUND if the source is missing, ERR_UNSUPPORTED_FMT for non-.docx sources, ERR_LIBREOFFICE_MISSING when soffice is not on PATH, ERR_EXPORT_FAILED for any other failure.

Replace every occurrence of find with replace.

Operates on every body paragraph. The reported replacements count is the sum of occurrences across all paragraphs before the replacement is applied (case-sensitivity follows the case_sensitive flag).

Args: path: Path to an existing .docx. find: The literal string to search for. Must be non-empty. replace: The replacement string. case_sensitive: When True (default), the match is exact; when False, the match is case-insensitive. folder: Optional base folder for relative paths.

Returns: {"replacements": <n>}.

Raises: OfficeMCPError: ERR_INVALID_PARAMS if find is empty or non-string, ERR_FILE_NOT_FOUND if the file is missing, ERR_UNSUPPORTED_FMT for non-.docx extensions.

Update the formatting of a single run.

Args: path: Path to an existing .docx. paragraph_index: Zero-based index of the paragraph. run_index: Zero-based index of the run inside that paragraph. bold: True / False to set, or None to leave as-is. italic: Same convention as bold. font_size: Point size (int or float) or None. font_name: Font name string or None. color: Hex color string (e.g. "FF0000") or None. folder: Optional base folder for relative paths.

Returns: {"ok": True}.

Special case: If all of bold, italic, font_size, font_name, color are None, the function is a no-op: the file is not re-saved and the SHA256 is preserved (VAL-WORD-039 / VAL-WORD-076).

Raises: OfficeMCPError: ERR_INVALID_PARAMS if indices are out of range or of the wrong type, or color is not a valid hex string. ERR_FILE_NOT_FOUND if the file is missing, ERR_UNSUPPORTED_FMT for non-.docx extensions.

Return counts and core properties of a .docx file.

The returned dict contains:

• paragraphs — number of body paragraphs (including the empty one emitted by :func:docx.Document).

• sections — number of sections in the document.

• tables — number of body tables.

• images — number of inline shapes (images).

• properties — subset of core_properties (title, author) that are populated.

Args: path: Path to an existing .docx. folder: Optional base folder for relative paths.

Raises: OfficeMCPError: ERR_FILE_NOT_FOUND if the file is missing, ERR_UNSUPPORTED_FMT if the extension is not .docx, ERR_INVALID_PARAMS if path is empty.

Return one dict per body paragraph.

Each entry has index, style, text, and runs keys. runs is itself a list of run dicts (see :func:_serialise_run).

Args: path: Path to an existing .docx. folder: Optional base folder for relative paths.

Raises: OfficeMCPError: ERR_FILE_NOT_FOUND if the file is missing, ERR_UNSUPPORTED_FMT for non-.docx extensions.

Return a single paragraph's content and metadata.

Args: path: Path to an existing .docx. index: Zero-based paragraph index. folder: Optional base folder for relative paths.

Raises: OfficeMCPError: ERR_INVALID_PARAMS if index is negative or out of range, ERR_FILE_NOT_FOUND if the file is missing, ERR_UNSUPPORTED_FMT for non-.docx extensions.

Configure a section's orientation and page size.

Args: path: Path to an existing .docx. orientation: "portrait" or "landscape" (case-insensitive). Any other value raises ERR_INVALID_PARAMS (VAL-WORD-065). page_size: A named page size such as "A4" (default), "Letter", "Legal", "A5", "Tabloid" or "B5" (case-insensitive). section_index: Zero-based section index (default 0). folder: Optional base folder for relative paths.

Returns: {"ok": True}.

Behavior: * Portrait: page_width = <width>, page_height = <height>. * Landscape: page_width = <height>, page_height = <width> (i.e. dimensions are swapped so the wider edge is horizontal).

Raises: OfficeMCPError: ERR_INVALID_PARAMS for an unknown orientation or page_size, ERR_FILE_NOT_FOUND if the file is missing, ERR_UNSUPPORTED_FMT for non-.docx extensions.