| excel_create_workbookA | 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. |
| excel_get_infoA | 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. |
| excel_list_sheetsA | 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. |
| excel_read_sheetA | 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. |
| excel_write_cellA | 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. |
| excel_write_rangeA | 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. |
| excel_create_sheetA | 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. |
| excel_delete_sheetA | 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. |
| excel_rename_sheetA | 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. |
| excel_format_cellsA | 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. |
| excel_add_chartA | 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. |
| excel_export_csvA | 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. |
| excel_export_pdfA | 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. |
| excel_export_htmlA | 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. |
| list_documentsA | 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. |
| get_document_infoA | 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. |
| search_textA | 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. |
| convert_documentA | 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). |
| pptx_create_presentationA | 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. |
| pptx_get_infoA | 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. |
| pptx_list_slidesA | 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
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. |
| pptx_read_slideA | 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. |
| pptx_add_slideA | 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. |
| pptx_delete_slideA | 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. |
| pptx_reorder_slidesA | 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. |
| pptx_add_text_boxA | 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. |
| pptx_add_imageA | 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. |
| pptx_add_shapeA | 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. |
| pptx_add_tableA | 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. |
| pptx_add_chartA | 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. |
| pptx_export_pdfA | 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. |
| pptx_export_htmlA | 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. |
| word_create_documentA | 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. |
| word_get_infoA | 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. |
| word_list_paragraphsA | 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. |
| word_read_paragraphA | 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. |
| word_add_paragraphA | 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. |
| word_add_headingA | 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. |
| word_find_replaceA | 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. |
| word_format_runA | 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. |
| word_add_tableA | 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. |
| word_add_imageA | 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. |
| word_add_headerA | 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. |
| word_add_footerA | 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. |
| word_set_sectionA | 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. |
| word_export_pdfA | 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. |
| word_export_htmlA | 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. |
