aiguicai/mcp-gateway/officecli

officecli

AI-friendly CLI for .docx, .xlsx, .pptx. Single binary, no dependencies, no Office installation needed.

IMPORTANT: How to Use This Tool

This is a dedicated built-in tool named officecli. You MUST follow these rules:

1. Do NOT use `shell_command` to run officecli commands. The gateway will block any attempt to run officecli through shell_command. Always use this officecli tool directly.

1. Executing commands (skillToken required):

• Every exec value MUST start with the officecli prefix.
• You MUST include the skillToken returned from reading this skill.
• Example: officecli({"exec": "officecli create report.docx", "skillToken": "<token>"})

1. The `exec` field always requires the `officecli` command prefix. Do NOT omit it.

• Correct: "exec": "officecli help"
• Correct: "exec": "officecli create file.docx"
• Wrong: "exec": "help"
• Wrong: "exec": "create file.docx"

1. Command snippets in this skill are CLI syntax. When this skill shows officecli ... in a code block, execute that command by putting the full line in the built-in tool's exec field with the required skillToken.

Prerequisites

The officecli binary must be installed and available in PATH before this tool can be enabled. Use officecli --version to verify. If not installed, enable it via the admin UI or install manually from https://github.com/iOfficeAI/OfficeCLI/releases.

Strategy

L1 (read) -> L2 (DOM edit) -> L3 (raw XML). Always prefer higher layers. Add --json for structured output.

Before document work, check Specialized Skills near the bottom of this file. Generic decks, pitch decks, Morph decks, academic papers, financial models, and dashboards need their own officecli load_skill <name> rules before creating or heavily editing the artifact. The base skill explains commands; the specialized skill explains document quality.

Help System (IMPORTANT)

When unsure about property names, value formats, or command syntax, ALWAYS run help instead of guessing. One help query beats guess-fail-retry loops.

officecli help is equivalent to officecli --help, and officecli <cmd> --help is equivalent to officecli help <cmd>.

Gateway execution examples:

officecli({"exec": "officecli help", "skillToken": "<token>"})
officecli({"exec": "officecli help docx", "skillToken": "<token>"})
officecli({"exec": "officecli help docx paragraph", "skillToken": "<token>"})
officecli({"exec": "officecli help docx set paragraph", "skillToken": "<token>"})
officecli({"exec": "officecli help pptx shape --json", "skillToken": "<token>"})

CLI syntax examples:

officecli help                                  # All commands + global options + schema entry points
officecli help docx                             # List all docx elements
officecli help docx paragraph                   # Full schema: properties, aliases, examples, readbacks
officecli help docx set paragraph               # Verb-filtered: only props usable with `set`
officecli help docx paragraph --json            # Structured schema (machine-readable)

Format aliases: word -> docx, excel -> xlsx, ppt/powerpoint -> pptx. Verbs: add, set, get, query, remove.

Resident Mode

Every command auto-starts a resident on first access when available, with a short idle timeout, so file-lock conflicts are automatically avoided. Explicit open/close is still recommended for longer sessions:

officecli({"exec": "officecli open report.pptx", "skillToken": "<token>"})
officecli({"exec": "officecli set report.pptx ...", "skillToken": "<token>"})
officecli({"exec": "officecli close report.pptx", "skillToken": "<token>"})

officecli open report.docx       # explicitly keep in memory
officecli set report.docx ...    # no file I/O overhead
officecli close report.docx      # save and release

Opt out of auto-start with OFFICECLI_NO_AUTO_RESIDENT=1.

Quick Start

PPT:

officecli({"exec": "officecli create slides.pptx", "skillToken": "<token>"})
officecli({"exec": "officecli add slides.pptx / --type slide --prop title=\"Q4 Report\" --prop background=1A1A2E", "skillToken": "<token>"})
officecli({"exec": "officecli add slides.pptx '/slide[1]' --type shape --prop text=\"Revenue grew 25%\" --prop x=2cm --prop y=5cm --prop font=Arial --prop size=24 --prop color=FFFFFF", "skillToken": "<token>"})

Word:

officecli({"exec": "officecli create report.docx", "skillToken": "<token>"})
officecli({"exec": "officecli add report.docx /body --type paragraph --prop text=\"Executive Summary\" --prop style=Heading1", "skillToken": "<token>"})
officecli({"exec": "officecli add report.docx /body --type paragraph --prop text=\"Revenue increased by 25% year-over-year.\"", "skillToken": "<token>"})

Excel:

officecli({"exec": "officecli create data.xlsx", "skillToken": "<token>"})
officecli({"exec": "officecli set data.xlsx /Sheet1/A1 --prop value=\"Name\" --prop bold=true", "skillToken": "<token>"})
officecli({"exec": "officecli set data.xlsx /Sheet1/A2 --prop value=\"Alice\"", "skillToken": "<token>"})

PowerPoint Quality Workflow

For .pptx, first load exactly one matching specialized skill:

officecli({"exec": "officecli load_skill pptx", "skillToken": "<token>"})

Then follow the rules it prints. At minimum:

• Set explicit geometry on every non-placeholder shape: x, y, w/width, h/height.
• Set explicit typography on text shapes: font, size, color, and alignment where supported.
• Use one idea per slide. Split dense bullet slides instead of shrinking text.
• Every content slide should include a non-text visual: shape system, picture, chart, icon, table, or diagram.
• Add speaker notes on content slides with --type notes when generating a real deck.
• Verify after generation with view outline, view stats --json, view issues --json, and a rendered preview (view html or view screenshot).
• Treat text overflow and off-slide geometry as blocking issues. Fix them before declaring the file done.

Common failure mode: creating only a title and one default text box per slide produces a valid PowerPoint file, but not a designed presentation. Default text boxes start at x=0cm y=0cm and 10cm x 5cm; they usually look unplaced and can overlap or overflow.

REQUIRED: WPS Compatibility Fix

OfficeCLI writes <Application>OfficeCLI/x.x.x</Application> into docProps/app.xml when creating files. WPS Office does not recognize this application identifier and will refuse to open the file ("format not recognized").

After every `officecli create`, you MUST run this cleanup step:

officecli raw-set <file> docProps/app.xml --xpath "//ap:Application" --action delete

Example full flow:

officecli({"exec": "officecli create report.docx", "skillToken": "<token>"})
officecli({"exec": "officecli raw-set report.docx docProps/app.xml --xpath \"//ap:Application\" --action delete", "skillToken": "<token>"})

This applies to all formats (.docx, .xlsx, .pptx). Do NOT skip this step.

L1: Create, Read & Inspect

officecli create <file>               # Create blank .docx/.xlsx/.pptx (type from extension)
officecli view <file> <mode>          # outline | stats | issues | text | annotated | html
officecli get <file> <path> --depth N # Get a node and its children [--json]
officecli query <file> <selector>     # CSS-like query
officecli validate <file>             # Validate against OpenXML schema

view modes

Use view html for one-shot snapshots (CI artifacts, archival, diffing); use watch when you need live refresh or browser-side click-to-select.

Useful render checks:

officecli view <file> html -o preview.html
officecli view <file> screenshot -o slide.png
officecli view <file> issues --json

get

Any XML path via element localName. Use --depth N to expand children. Add --json for structured output. Default text output is grep-friendly: path (type) "text" key=val key=val ...

officecli get report.docx '/body/p[3]' --depth 2 --json
officecli get slides.pptx '/slide[1]' --depth 1          # list all shapes on slide 1
officecli get data.xlsx '/Sheet1/B2' --json

Stable ID Addressing

Elements with stable IDs return @attr=value paths instead of positional indices. Prefer these in multi-step workflows because positional indices shift on insert/delete, while stable IDs do not.

/slide[1]/shape[@id=550950021]                    # PPT shape
/slide[1]/table[@id=1388430425]/tr[1]/tc[2]       # PPT table
/body/p[@paraId=1A2B3C4D]                         # Word paragraph
/comments/comment[@commentId=1]                    # Word comment

PPT also accepts @name= (for example shape[@name=Title 1]), with morph !! prefix awareness. Elements without stable IDs (slide, run, tr/tc, row) fall back to positional indices.

query

CSS-like selectors: [attr=value], [attr!=value], [attr~=text], [attr>=value], [attr<=value], :contains("text"), :empty, :has(formula), :no-alt.

officecli query report.docx 'paragraph[style=Normal] > run[font!=Arial]'
officecli query slides.pptx 'shape[fill=FF0000]'

Watch & Interactive Selection

Live HTML preview that auto-refreshes on every file change. Browsers can click, shift-click, or box-drag to select shapes; the CLI can read the current browser selection and act on it.

officecli watch <file> [--port N]      # Start preview server (default port 26315)
officecli unwatch <file>               # Stop
officecli goto <file> <path>           # Scroll watching browser(s) to element (docx: p / table / tr / tc)

Open the printed http://localhost:N URL. Click to select; shift/cmd/ctrl-click to multi-select; drag from empty space to box-select. PPT/Word use blue outline; Excel uses native-style green selection (double-click cell to edit inline; drag a chart to reposition).

get <file> selected - read what the user clicked

officecli get <file> selected [--json]

Returns DocumentNodes for whatever is currently selected. Empty result if nothing selected. Exit code is nonzero if no watch is running.

# User clicks shapes in the browser, then asks "make these red"
PATHS=$(officecli get deck.pptx selected --json | jq -r '.data.Results[].path')
for p in $PATHS; do officecli set deck.pptx "$p" --prop fill=FF0000; done

Key properties

• Selection survives file edits. Paths use stable @id= form.
• All connected browsers share one selection. Last-write-wins.
• Same-file single-watch. A given file can have only one watch process at a time.
• Group shapes select as a whole. Drilling into individual children of a group is not supported in v1.
• Coverage: .pptx shapes/pictures/tables/charts/connectors/groups; .docx top-level paragraphs and tables. Inherited layout/master decorations and Word nested elements (table cells, run-level) are not addressable. `.xlsx` does not emit `data-path`; mark/selection on xlsx always resolve stale=true.