mcp-genoffice

MCP server that gives AI agents byte-preserving, surgical editing of Office documents through the GenOffice engine packages (Apache-2.0, pure TypeScript, no Electron required).

The core guarantee, inherited from GenOffice's architecture: the original file is the source of truth. Only the blocks you edit are regenerated as OOXML fragments; every untouched paragraph, style, header, comment and zip part keeps its original bytes. Layout never breaks.

Tools

Tool	Description
genoffice_extract_text	Extract readable text from .docx / .xlsx / .pptx / .pdf (slides/table structure preserved)
genoffice_docx_blocks	Parse a .docx and list top-level blocks (index, type, style, text)
genoffice_docx_patch	Rewrite one or more paragraphs with a byte-preserving roundtrip; optional formatting per edit (bold/italic/color/sizePt/font); writes a new file, never touches the original
genoffice_docx_watermark	Set/remove a text watermark (header regenerated, body byte-preserved)
genoffice_docx_create	Create a NEW .docx from scratch (optional initial paragraphs, each with optional formatting)
genoffice_docx_delete	Delete blocks (paragraphs/headings) — remaining blocks byte-preserved
genoffice_pptx_slides	List slides and their text elements (id, name, type, text)
genoffice_pptx_patch	Replace text of elements on a slide (element-level byte-preserving); optional formatting per edit (bold/italic/color/sizePt/font)
genoffice_pptx_create	Create a NEW .pptx from scratch (one blank slide)
genoffice_pptx_delete	Delete elements from a slide (other slides/parts byte-preserved)
genoffice_app_status	GenOffice desktop app: installed? CDP port up? (read-only)
genoffice_app_launch	Launch the app with the CDP debug port (handles auto-update relaunch)
genoffice_app_open_file	Open a file in the app (macOS open -a, registered doc types)
genoffice_app_screenshot	PNG screenshot of the app window over CDP
genoffice_app_eval	Evaluate read-only JS in the app page context (DOM)

More tools (xlsx ops) are on the roadmap.

Install / run

# from source
npm install
npm start

# as a library in your MCP client (Hermes, Claude Desktop, ...)
npx -y mcp-genoffice

Configure in Hermes (~/.hermes/config.yaml):

mcp_servers:
  genoffice:
    command: "npx"
    args: ["-y", "mcp-genoffice"]
    env:
      # optional: point at your own genoffice clone; otherwise the server
      # auto-clones the pinned revision into ~/.cache/mcp-genoffice/src
      # GENOFFICE_SRC: "/path/to/genoffice"
    timeout: 300
    connect_timeout: 120

How the engines are loaded

The GenOffice engine packages are not published to npm and ship as TypeScript source. The server loads them from a checkout of genspark-ai/genoffice in two ways:

1. GENOFFICE_SRC env var — use your own clone (fast, dev mode).
2. Auto-clone (default) — a shallow, SHA-pinned checkout (GENOFFICE_PIN in src/engine.ts) plus npm install on first use.

The server runs under the tsx loader so the TS-source engines import cleanly.

Development

npm install
npx tsc --noEmit          # typecheck
node tests/client.mjs     # end-to-end: spawns the server, lists tools, patches a fixture

The e2e test uses fixture files from a genoffice clone. By default it points at /tmp/genoffice; override with FIXTURE_SRC. Unset SERVER_SRC to exercise the auto-clone path.

Roadmap

• Headless engine mode (extract + docx blocks + docx patch)
• genoffice_docx_patch rich options (styles, headers, comments, watermark)
• PPTX / XLSX tools (pptx-engine, sheets sidecar)
• CDP mode: drive the installed GenOffice app (launch, open file, AI edit)
• Hermes MCP catalog entry (optional-mcps/genoffice) + usage skill

License

MIT. The GenOffice engine packages are Apache-2.0 (loaded at runtime from a user-provided or auto-cloned checkout, never bundled).