Skip to main content
Glama

OfficeAgent.NET

build NuGet .NET 10 API: SemVer 1.x stable native Office: 94/94 cases verified OpenSSF Best Practices OpenSSF Scorecard good first issues license

OfficeAgent.NET lets an AI agent or a .NET application edit your own Word, PowerPoint and Excel files without breaking them:

  • Fill your company's Word template: content controls, bookmarks and repeating table rows, returned as the same file with its styles, numbering, headers and comments intact.

  • Build slides on your own PowerPoint template: new slides on the template's own layouts, with named shapes, tables, charts and pictures filled and the logo and fonts left alone.

  • Change clauses, prices or dates as real tracked changes that Word can accept or reject.

Every change is a typed plan that is previewed first, and if any check fails nothing is written. It is built on Microsoft's Open XML SDK and runs without Office installed.

OfficeAgent.NET finds, previews, and applies a contract edit as a tracked change in Word.

Use it from

Start with

Claude Code, Codex, Cursor or any MCP client, with no .NET installed

uvx officeagent-mcp --stdio, pointed at a folder as in Try a Word edit

Claude Desktop

the one-click bundle in Standalone downloads

A .NET application, with or without an agent

dotnet add package OfficeAgent.Word, then Getting started

What this project does

An Office Open XML file is a package of related XML parts. A small change can affect runs, styles, numbering, comments, content controls, or revision markup. OfficeAgent.NET handles that document-specific work. The model works with structured document data and JSON-serialisable operations such as "replace this clause as a tracked change" or "add a row to this table."

The same engine is available in three forms:

  • an MCP server for agents that support the Model Context Protocol;

  • tools for Microsoft Agent Framework and Microsoft.Extensions.AI;

  • a .NET API for applications that want to control the workflow directly.

It supports Word .docx, PowerPoint .pptx, and Excel .xlsx; one client routes each document to the module that handles it. See Scope and limitations before choosing it for a workflow that depends on Office's layout or calculation engine.

What you can build

Area

Supported workflows

Word creation and editing

Create .docx files, blank or from a .docx or .dotx template; inspect and change text, paragraphs, tables, images, styles, content controls, headers, footers, notes, page setup, and document properties; replace a picture and keep its frame

Word review

Read and manage comments, preserve or resolve review state, set one revision identity per plan, and record supported edits as tracked revisions, marking only the changed words if you choose

PowerPoint creation and editing

Build decks, blank or from a .pptx or .potx template, or update them with slides on the template's own layouts, text, tables, native editable charts, images, media, notes, comments, sections, transitions, and animations

Excel inspection and editing

Inspect worksheets, tables, and bounded ranges; read cells as Excel displays them; find raw or displayed values; set cells and formulas; append table rows; manage cell notes

Report refresh

Update the numbers, tables and charts of a Word report or PowerPoint deck from an Excel workbook, through links the document keeps for next month

Translation and bulk edits

Rewrite a paragraph in another language and keep its formatting; change every match of a phrase; apply one plan to up to 100 documents

Template generation

Find the organization's templates, bind unique Word content-control tags or PowerPoint shape names, expand repeating Word table rows, and create bounded batches with one receipt per output

Word comparison

Compare supported free-body paragraph text read-only and produce a snapshot-bound native redline plan only when all other package content is unchanged

Agent and application integration

Use MCP over stdio or HTTP, Microsoft Agent Framework tools, or the direct .NET API, with SHA-256 apply receipts and host-supplied audit actors

Document access

Work with bounded filesystem roots, SharePoint, iManage Work, Google Drive, Box, Azure Blob Storage, Amazon S3, in-memory sessions, or self-contained inline content; list a connection's documents and templates

Related MCP server: docx-mcp

Choose a starting point

I want to...

Start here

Decide whether OfficeAgent fits my application

Library selection guide

Try a targeted Word edit

Try a Word edit

Use OfficeAgent in Claude Desktop, or run the server without .NET (from 1.2.0)

Standalone downloads

Run the server from PyPI with uvx officeagent-mcp, with no .NET installed

Install and run

Try the server and both skills as a Claude Code plugin

Claude Code plugin

Create a Word document from scratch

Create a document

Create or edit a PowerPoint deck

PowerPoint support

Inspect or edit an Excel workbook

Excel support

Connect Codex, Claude Code, Google ADK, Copilot Studio, Microsoft 365 Copilot, Microsoft Foundry, or ChatGPT

Deployment and client setup

Use OfficeAgent from C#

Getting started

Add tools to a Microsoft Agent Framework agent

Agent integration

Add tools to a Semantic Kernel agent

SemanticKernelWordEdit sample

Use OfficeAgent from Python with the OpenAI Agents SDK or LangGraph

python-openai-agents and python-langgraph samples

Give Microsoft 365 Copilot a contract redline reviewer

M365ContractReviewer sample

Host the MCP server, or keep documents in SharePoint, iManage Work, Google Drive, Box, Azure Blob Storage, or Amazon S3

MCP server and document providers

Deploy the server to Azure Container Apps

Azure deployment

Add the server to Copilot Studio as a custom connector

Copilot Studio connector

Start new documents from the organization's templates

List documents and templates and Office template locations

Add per-user hosted connection authorization

Hosted gateway reference

Add optional PDF/page-image rendering

Visual rendering

Edit documents with no storage configured

Documents with no storage

Run a tracked-review workflow

Optional word-document-review skill

Build a .NET, MCP, or Agent Framework integration

Optional officeagent-integration skill

Build a contract-review agent

ContractReview sample

Populate quote templates or compare Word documents

Template and comparison workflows

Update this month's report or deck from the new workbook

Report refresh

Translate a document and keep its formatting

Translate a document

Rename a company or update a disclaimer across a folder

Edit many documents at once

Check support, compatibility, or security policy

Support and security

Contribute

Contributing

Try a Word edit

This small workflow demonstrates that OfficeAgent can change an existing OOXML file without flattening its structure. It uses tracked changes because the result is easy to verify in Word; review is one part of the broader document operation set.

Install the exact server version documented by this release:

dotnet tool install --global OfficeAgent.Mcp --version 1.3.0

Make a folder for the agent to work in and download the sample contract into it — a fictional services agreement with a clause to change, a table, an open comment, and a pending redline:

mkdir -p ~/officeagent-documents
curl -Lo ~/officeagent-documents/services-agreement.docx \
  https://raw.githubusercontent.com/ilia-sokolov/OfficeAgent.NET/v1.3.0/samples/documents/services-agreement.docx

PowerShell:

$officeAgentDocuments = Join-Path $env:USERPROFILE "officeagent-documents"
New-Item -ItemType Directory -Force $officeAgentDocuments | Out-Null
Invoke-WebRequest `
  https://raw.githubusercontent.com/ilia-sokolov/OfficeAgent.NET/v1.3.0/samples/documents/services-agreement.docx `
  -OutFile (Join-Path $officeAgentDocuments "services-agreement.docx")

Any .docx of your own works too — the sample just gives you something with a comment and a pending revision already in it.

Register the server with Claude Code, pointed at that folder and nothing else:

claude mcp add \
  --env OfficeAgent__FileSystemConnections__0__ConnectionId=documents \
  --env OfficeAgent__FileSystemConnections__0__RootPath=$HOME/officeagent-documents \
  --transport stdio \
  officeagent -- officeagent-mcp --stdio

PowerShell:

claude mcp add `
  --env OfficeAgent__FileSystemConnections__0__ConnectionId=documents `
  --env "OfficeAgent__FileSystemConnections__0__RootPath=$officeAgentDocuments" `
  --transport stdio `
  officeagent -- officeagent-mcp --stdio

For this review-specific workflow, you can optionally install the word-document-review skill before starting the client.

Then ask:

In services-agreement.docx, change the payment terms from thirty days to forty-five days.

Expected result when the client invokes OfficeAgent correctly: apply_plan reports writeOutcome: "committed" and returns an output id, and clause 3 reads forty-five days as a tracked change you can accept or reject. Open that output in Word and verify the change. The regression test also verifies that the sample's existing table, comment, earlier payment redline, and heading remain present with their tested XML semantics. It does not claim byte-for-byte identity for every unrelated OOXML part; see the bounded preservation evidence.

If the agent did not call apply_plan, or if writeOutcome is not committed, do not report the edit as complete. For unknown or writtenNotRegistered, preserve possibleOutput and follow storage recovery instead of retrying blindly.

What else the sample is good for — reviewing comments, accepting revisions, editing the table.

Next, try creating a Word document, generating a PowerPoint deck, or using the direct .NET workflow.

If it does not work

claude mcp list shows officeagent as failed

Check RootPath is an absolute path to a directory that exists.

The agent says it cannot find the document

Use a relative name, or an absolute path that still resolves inside RootPath.

io-error on save

Close the file in Word, then check filesystem permissions and the available disk space.

outcome-unknown or registration-failed

Do not repeat the edit. Preserve possibleOutput and follow the recovery procedure to determine whether the output already exists.

Configure broader workflows

The quick start above is deliberately the smallest thing that works. Four settings extend it:

Setting

Adds

OfficeAgent__AllowCreation=true

create_document, so "draft a project brief in brief.docx" makes a new file instead of failing

OfficeAgent__FileSystemConnections__0__AllowedExtensions__0=.docx plus OfficeAgent__FileSystemConnections__0__AllowedExtensions__1=.pptx

Word and PowerPoint on one connection. Declaring this list replaces the .docx default. Set OfficeAgent__FileSystemConnections__0__DefaultChangeMode=Direct for decks, and send "mode": "Tracked" explicitly for reviewable Word edits on that mixed connection.

OfficeAgent__EphemeralConnectionId=session

Names the in-memory session connection explicitly. With no configuration at all the server already falls back to one - this is for running it alongside storage, or under a different id

OfficeAgent__AllowInlineContent=true

Tools that carry the document as base64, for a single self-contained call

Past a couple of settings, use a file instead — the same OfficeAgent section, where a list is a list:

{
  "OfficeAgent": {
    "AllowCreation": true,
    "FileSystemConnections": [
      {
        "ConnectionId": "documents",
        "RootPath": "C:\\officeagent-documents",
        "AllowedExtensions": [ ".docx", ".pptx" ],
        "DefaultChangeMode": "Direct"
      }
    ]
  }
}

The same configuration is available as samples/config/word-and-powerpoint.json. Change RootPath before using it.

claude mcp add --transport stdio officeagent -- officeagent-mcp --stdio --config ./officeagent.json

Environment variables still override the file. Windows, PowerShell, other MCP clients, HTTP hosting and SharePoint are in Deployment and client setup; every setting is listed in MCP server.

Optional guidance for Word review

skills/word-document-review teaches the review loop: read comments and pending revisions before editing, keep reviewable Word edits as redlines, use document ids for multi-step work, and recover from stable error codes. The installation guide gives complete Bash and PowerShell steps for Claude Code and Codex, including installation from a fresh machine and verification. The skill is only needed when the task requires that review discipline; document creation, ordinary direct edits, and PowerPoint workflows use the server without it.

Optional guidance for application integration

skills/officeagent-integration helps an implementation agent choose the direct .NET API first, add MCP or Microsoft Agent Framework only when needed, and run installed-package recipes for tracked editing, template population, and complete-plan comparison. The installation guide covers both skills and makes clear that a skill does not install the runtime, NuGet packages, or MCP server.

What reaches the model

The inspect and find tools return document text and structure to the model — that is how it locates an edit. Operations on a storage connection keep the package behind an opaque id. Inline tools carry the whole file as base64 on every call. Session import/export also carries the package as base64 if the agent performs those calls; a host integration can instead move the bytes outside model context. Connect storage and model providers appropriate for the data.

The standalone server ships no authentication layer for HTTP hosting; put it behind your own, or start from the authenticated HostedGateway reference. A filesystem root is a trust boundary: its ACLs must stop untrusted principals creating, renaming or replacing entries while the server runs.

.NET quick start

Install the core package and Word module:

dotnet add package OfficeAgent.Core
dotnet add package OfficeAgent.Word

After registering services and a document provider, the edit loop looks like this:

var client = services.GetRequiredService<OfficeAgentClient>();
var doc = await client.RegisterAsync("workspace", "/srv/workspace/contract.docx");

var inspect = await client.InspectAsync("workspace", doc.ItemId);
var hit = (await client.FindAsync(
    "workspace", doc.ItemId, new FindQuery("Acme Corp"))).First();

var plan = new DocumentPlan
{
    Snapshot = inspect.Snapshot,
    Revision = new RevisionMetadata { Author = "OfficeAgent Quickstart" },
    Operations = new PlanOperation[]
    {
        new ChangeTextOp
        {
            Target = hit.Anchor,
            With = "Globex Inc.",
            Mode = ChangeMode.Tracked
        }
    }
};

var preview = await client.PreviewAsync("workspace", doc.ItemId, plan);
if (preview.IsValid)
    await client.CommitAsync("workspace", doc.ItemId, plan);

Revision.Author is the name Word displays for the tracked change. It is not an authenticated actor identity. See revision identity and audit receipts.

The complete example, including service registration and reading the saved file, is in Getting started. The minimal direct-.NET sample runs against the bundled fictional contract, so it needs no MCP client, language model, or document of your own:

dotnet run --project samples/QuickEdit -- \
  samples/documents/services-agreement.docx quickedit-output.docx

Open quickedit-output.docx in Word and verify that the payment term is a tracked change while the existing revision, comment, table, and headings remain intact. QuickEdit also accepts an exact source and replacement text for your own document. Releases also attach quickedit-sample.zip, a package-backed copy that runs outside the repository against the released NuGet packages.

The repository also contains a direct IChatClient Word-editing sample and an interactive Agent Framework sample, plus a complete contract-review agent that separates model judgement from validated document writes. The TemplateBatch sample generates two quotes from one tagged template, while DocumentComparison turns covered body-paragraph differences into a reviewable Word redline. The DocumentAssembly sample combines a proposal, statement of work, and appendix into one editable package with a multi-source audit receipt. See Word document assembly for its formatting and compatibility scope. LiabilityCap changes a value in a commented table cell as a tracked change, TableRowInsertion adds a table row as a tracked change and keeps the existing comments, and PageCounter counts rendered pages with the optional rendering package.

How it works

Every edit follows the same four steps:

  1. Inspect returns a structured map of the document: its outline, paragraphs, styles, content controls, tables, images, and revisions.

  2. Find searches text and returns a content-verified anchor for each match.

  3. Preview validates a plan against the current document and reports the proposed changes without writing.

  4. Apply commits the complete plan and saves it through the configured provider.

A plan (DocumentPlan) is a typed, JSON-serialisable list of operations. An anchor records both a location and the content expected there. If the content or optional document snapshot has changed, validation fails instead of silently targeting a different location. All operations are applied to one in-memory transaction or none are; a later provider failure can still leave storage uncertain, so callers must inspect writeOutcome before retrying.

The Word module supports changes to text, paragraphs, tables, images, styles, content controls, comment threads, footnotes and endnotes, page geometry and breaks, document properties, and tracked revisions. Operations with a Word revision representation record a redline when the connection asks for one - an inserted clause, a deleted row and a restyled heading all come back as revisions a reviewer accepts or rejects, not only a replaced phrase. Image resizing is applied directly because WordprocessingML has no revision representation for drawing dimensions. The PowerPoint module implements a broad, explicitly documented set of deck operations: text, bullets, run and paragraph formatting, template slots, style copying, tables, images, text boxes, embedded video and audio, speaker notes, resolvable comments, footers and slide numbers, sections, transitions and animations, and the slide lifecycle - adding, removing, reordering and duplicating. Several slide inserts in one plan author a deck end to end, so a single call turns nothing into a finished presentation. Any verb it does not support is named rather than silently skipped. The full operation schema is documented in Document plans, and the deck specifics in PowerPoint support.

Documents are accessed through configured providers. After registration, editing calls use a (connectionId, documentId) pair instead of a storage path or credentials. The filesystem provider restricts registrations to its root; the SharePoint, iManage Work, Google Drive and Box providers use the permissions of their configured identity, and the Azure Blob Storage and Amazon S3 providers keep registrations under the connection's prefix. CreateAsync starts a new document inside a connection: the requested .docx, .pptx or .xlsx extension selects a registered blank-document factory. CreateFromTemplateAsync starts it as a copy of a template instead, and only reads the template; a .dotx, .potx or .xltx template becomes a normal .docx, .pptx or .xlsx. The engine applies an optional initial plan in memory, and then asks the provider to create and register it without overwriting an existing name.

Documentation

Guide

Covers

Documentation hub

Learning paths, package map, and the complete documentation set

Library selection guide

Supported jobs, non-goals, package choices, alternatives, and a verified direct .NET recipe

Getting started

A complete edit from service registration to reading the result

Concepts

Anchors, snapshots, plans, providers, transactions, and capabilities

C# API reference

Generated public types and members for every library package

Document plans

JSON shapes and validation rules for every operation

Document providers

Filesystem, SharePoint, iManage Work, Google Drive, Box, Azure Blob Storage, Amazon S3, listing, templates folders, save modes, and custom providers

PowerPoint support

Slide addressing, the verbs the deck module implements, and what it preserves

Template population and comparison

Creating from a template, batch binding, repeating Word rows, comparison limits, and redline generation

Report refresh

Linking a report or deck to workbook ranges and refreshing it in one call

Translation and bulk edits

Translating with formatting kept, and one plan across many documents

Agent integration

Microsoft Agent Framework and Microsoft.Extensions.AI tools

MCP server

Server configuration, transports, security notes, and tool contracts

Deployment and client setup

Codex, Claude Code, Google ADK, Microsoft Copilot clients, Microsoft Foundry, ChatGPT, containers, and Azure

Operations

Concurrency, streams, cancellation, telemetry, and production concerns

Troubleshooting

Startup, registration, validation, concurrency, and provider failures

Failure modes

Common plan errors and what to do next

Releasing

Publishing to NuGet, PyPI, the MCP Registry, and GitHub

Contributing

Bug reports, documentation fixes, new document operations, provider integrations, and focused test cases are useful contributions. If you found a problem, open an issue with the document feature involved, the operation you attempted, and the error or unexpected result. Do not attach confidential documents; a small sanitised reproduction is enough.

To work on the code, install the .NET 10 SDK, fork the repository, and run:

dotnet build OfficeAgent.NET.sln
dotnet test OfficeAgent.NET.sln

Before starting a larger change, especially one that changes public types or the JSON wire format, open an issue so the design can be discussed. See CONTRIBUTING.md for code style, tests, and pull-request expectations.

Scope and limitations

OfficeAgent.NET edits Word .docx, PowerPoint .pptx, and Excel .xlsx files; it does not automate the Office desktop applications. It does not decrypt: a file protected by a sensitivity label or a password is refused with encrypted-document. It does not start a document from a macro-enabled template or document, which is refused with macro-enabled-document.

The deck module refuses the verbs a presentation has no vocabulary for - setProperty, revision, pageSetup, insertBreak and note - per operation, rather than applying part of a plan, and refuses an explicit tracked mode on any verb that carries one. PresentationML has no redline model, so tracked changes are Word-only, and a slide has no header (that is a notes and handout concept). Animations cover the effects expressible as a filtered p:animEffect; fly-in, zoom and motion paths are refused rather than approximated. See PowerPoint support for what a deck does and does not accept.

The core engine does not render pages, calculate Word fields, or evaluate Excel formulas. Formula edits set the workbook to recalculate when Excel opens it. The optional OfficeAgent.Excel.Calculation package calculates a verified set of Excel functions and writes the results as cached values; see formula calculation. Operations that depend on pagination, table-of-contents rendering, or field recalculation are outside the core scope. Preview reports structural changes. The optional rendering package can produce PDF-derived page images through external processes, but it does not yet detect overflow or page-fit problems. Test the workflow on representative documents and keep human review in the loop for consequential edits.

Two more limits worth knowing before you build on it:

  • Token savings depend on how you connect. Addressing a document by id keeps the package out of the conversation, and inspection can be narrowed with fidelity and paging - that is where the saving comes from. The inline *_content tools are the deliberate exception: they carry the whole file as base64 in both directions, which costs tokens in proportion to file size. They suit a single self-contained call, not a sequence of edits - a model asked to pass a document of a few kilobytes back for a second edit reproduces it imperfectly and the follow-up fails. Use a connection, or a session connection, when more than one edit is coming.

  • Review guidance is optional. For review tasks, the server alone does not make an agent read open comments before editing or choose a redline. The word-document-review skill teaches that workflow; without it, review behaviour depends on the model and the prompt.

Commercial support

OfficeAgent.NET is MIT-licensed and can be self-hosted. Commercial support and deployment assistance are available from dotaction: contact dotaction. That service is separate from the project: it is governed by its own agreement and does not change the library's license, compatibility promise or community support policy.

Privacy Policy

OfficeAgent.NET runs on your machine or your own server and collects nothing: no telemetry, no analytics, no calls home. It reads and writes only the documents in the folders, SharePoint libraries, other document stores, or session connections it is given, and contacts no third party except the storage service of a connection a host configures: SharePoint, iManage Work, Google Drive, Box, Azure Blob Storage or Amazon S3. Tool results go to the AI assistant using it, under that assistant's own policy. The full policy, including what is stored and for how long, is in PRIVACY.md.

License

MIT. See LICENSE.

Available Tools

16 tools
apply_planApply an edit planA
Destructive

Apply a DocumentPlan JSON to (connectionId, documentId) and save through the provider. Returns {isValid, committed, writeOutcome, possibleOutput, receipt, sourceDocumentId, outputConnectionId, outputDocumentId, outputVersion, outputName, outputContentType, changes, errors, calculation}; non-applicable values are null. The receipt hashes the effective plan and exact input/output bytes and keeps the host-authenticated actor separate from the plan's display revision author. saveMode: 'Replace' (default, overwrites the source after an optimistic version check), 'NewVersion' (keeps the source and mints a new id under the same connection), 'NewDocument' (mints a fresh id with an optional newName for display). Plan-validation and operation-conflict failures have writeOutcome 'notWritten'. A provider failure after a write began may instead return 'unknown' or 'writtenNotRegistered' with possibleOutput; never retry those blindly or report the document unchanged until the host reconciles the possible output.

Inputs: newName (required), planJson (required), saveMode (required), documentId (required), +1 more.

compare_documentsCompare two documentsA
Read-onlyIdempotent

Read two Word documents and return paragraph differences, exact input SHA-256 hashes, coverage diagnostics, and a tracked-change plan bound to the original snapshot. Covered: text added, removed or changed in free body paragraphs, and text changed inside a table cell when the table's geometry is unchanged. The same words split differently across equally formatted runs are not a difference, because Word re-segments runs constantly. Refused, with a per-area diagnostic and no plan: changed table geometry, a cell whose formatting changed along with its words, paragraph formatting or style changes, and changes in headers, footers, notes, images, numbering or other parts. Differences found in the areas that are covered are still reported when another area blocks the plan, so a refusal tells you what it saw. Unsupported changes make isComplete false and plan null. This tool writes nothing; preview and apply the returned plan against the original document.

Inputs: revisionAuthor (required), revisedDocumentId (required), originalDocumentId (required), revisedConnectionId (required), +1 more.

describe_capabilitiesDescribe capabilitiesA
Read-onlyIdempotent

List what this server actually supports before planning an edit: the accepted edit-plan contract version, every registered format with the plan verbs and change modes it takes, the host's document size and expansion ceilings, and the connections you may use with the capabilities you hold on each. A verb missing from a format is not supported there and will be refused. Anchor ids are never listed: they come from inspect_document for the document in hand.

Inputs: no named parameters.

edit_documentEdit a documentA
Destructive

Edit a document the user named by source, in one call: registers it, resolves targets, and applies the operations - use this instead of register_document + find_in_document + apply_plan. planJson is an operations array [ … ] or { "operations": [ … ] }, the same operations preview_plan documents. Targets may name text directly instead of a paragraph id, so no lookup call is needed first: { "op": "changeText", "target": { "find": "Acme Corp" }, "with": "Globex Inc." } If that text matches more than once the call fails with 'ambiguous-anchor' and lists each candidate with its context; re-issue with { "find": "Acme Corp", "match": 2 } (zero-based) or use more surrounding text. Text that matches nothing fails with 'anchor-not-found'. { "find": "Acme Corp", "match": "all" } repeats the operation for every match - every one in headers, footers and notes too - and skips it where there is none. find ignores case and matches inside words unless the target adds "caseSensitive": true or "wholeWord": true. Anchors resolved from inspect_document/find_in_document ({ "paraId": …, "expect": … }) work here too, and can be mixed in the same plan. saveMode and newName behave as in apply_plan. Nothing is written unless every operation validates. Returns the apply_plan shape plus sourceDocumentId - the id of the document that was opened, usable for follow-up calls even when the edit failed.

Inputs: source (required), newName (required), planJson (required), saveMode (required), +1 more.

edit_documentsEdit several documentsA
Destructive

Apply one plan to several documents in one call - rename a company, update a disclaimer, or change a term across a folder. sources lists up to 100 documents, each exactly as edit_document takes source; list the folder yourself first. Name text with "match": "all" so each document changes wherever the text appears: { "op": "changeText", "target": { "find": "Acme Corp", "match": "all", "caseSensitive": true }, "with": "Globex Inc." }. find ignores case and matches inside words unless the target adds "caseSensitive": true or "wholeWord": true; a rename usually wants both. Each document is edited on its own and atomically: one that fails is left untouched and the others still save. A document in which no "match": "all" target matched is reported as unchanged and not saved. Run with preview=true first to see every document's changes without writing anything, then again without it. The plan cannot carry a snapshot. saveMode behaves as in apply_plan; NewDocument keeps each source and saves a new copy beside it. Returns {isValid, preview, summary: {total, committed, previewed, unchanged, failed, notAttempted}, items}; each item is {source, status} followed by exactly what edit_document returns for that document, receipt included.

Inputs: preview (required), sources (required), planJson (required), saveMode (required), +1 more.

find_in_documentFind in a documentB
Read-onlyIdempotent

Find content in Word, PowerPoint, or Excel. Excel can search displayed, raw, or both cell representations and returns sheetId plus A1 address anchors.

Inputs: regex (required), pattern (required), wholeWord (required), documentId (required), +3 more.

find_templatesFind templatesA
Read-onlyIdempotent

Find templates in every connection that has a template location: an organization library, a workgroup or personal Office templates folder, or a templates folder in a connection. format is word, powerpoint, excel, or "" for all; nameContains keeps names containing it, ignoring case. Returns {templates: [{connectionId, source, name, folder, format, location}], connectionsSearched, connectionsFailed: [{connectionId, code, message}]}, best match first; location is organization, workgroup, personal or connection. Pass connectionId and source to open_document, or as create_document's template source.

Inputs: format (required), nameContains (required), maximumResults (required).

inspect_documentInspect a documentA
Read-onlyIdempotent

Inspect a Word, PowerPoint, or Excel document. Excel returns worksheets, tables, and a bounded cell list; use sheetId, range, and maximumCells to narrow it. Other formats return their outline, paragraphs, content controls, nodes, and styles. Copy anchors and node paths from this result.

Inputs: range (required), sheetId (required), fidelity (required), documentId (required), +4 more.

list_connectionsList connectionsA
Read-onlyIdempotent

List the connections you can address documents under. Returns [{connectionId, provider, canCreateDocuments, allowedExtensions, defaultChangeMode, defaultChangeGranularity, calculatesFormulas, listable, templatesFolder, templateLocation, readOnly}] where provider names the storage, such as "filesystem" or "sharepoint"; listable says list_documents works on it, templateLocation (organization, workgroup, personal, connection, or null) says it holds templates, and readOnly true means it is never written to. Use a connectionId as the connectionId for register_document and the document tools; never ask the user for it.

Inputs: no named parameters.

list_documentsList documents in a connectionA
Read-onlyIdempotent

List the documents in a connection without opening them, to find a file the user named. folder is a folder in the connection, "" for its root; nameContains keeps names containing it, ignoring case; extensions is a comma list such as '.docx,.dotx', "" for every extension the connection allows; recursive includes subfolders; templates=true lists the connection's templates folder instead. Returns {connectionId, items: [{source, name, folder, contentType, length, lastModified, isTemplate}], continuation}. Pass an item's source to open_document or edit_document, or as create_document's template source. When continuation is not empty, call again with it and the same arguments for the next page.

Inputs: folder (required), recursive (required), templates (required), extensions (required), +4 more.

open_documentOpen a documentA

Open a document the user named by source: registers it and returns its inspection in one call - use this instead of register_document followed by inspect_document. source is connection-specific: for a filesystem connection, a path under its root. Returns {connectionId, documentId, name, contentType, version} followed by the inspect_document payload (snapshot, outline, paragraphs, contentControls, nodes, styles). Keep documentId for follow-up calls; paging works as in inspect_document.

Inputs: range (required), source (required), sheetId (required), fidelity (required), +4 more.

preview_document_mergePreview a document mergeA
Read-onlyIdempotent

Preview ordered whole-document Word assembly without saving. requestJson contains sources [{connectionId, documentId}] in output order and optional options {title, author}. Returns a merge plan bound to exact input hashes, source counts, identifier remapping decisions, and blocking diagnostics. Source formatting is preserved within the documented compatibility scope; each document starts on a new page. This is assembly, not reconciliation of edited versions.

Inputs: requestJson (required).

preview_planPreview an edit planA
Read-onlyIdempotent

Dry-run a DocumentPlan JSON against (connectionId, documentId). Returns {isValid, committed, receipt, sourceDocumentId, outputConnectionId, outputDocumentId, outputVersion, outputName, outputContentType, changes, errors, calculation}; the output fields are null and committed is false. Plan shape: { "snapshot": { "eTag": "" }, "revision": { "author": "Review Bot", "timestampUtc": "2026-09-09T10:00:00Z" }, "operations": [ ... ] }. revision controls Word's displayed revision identity; omit timestampUtc to use one engine timestamp for the whole apply. The snapshot detects drift in Word text-host XML, PowerPoint slide/notes XML, and Excel workbook, worksheet, table and note XML; other parts rely on anchors and provider version checks. Omit it only intentionally. Omit contractVersion for legacy 0.2 behavior, or set it to exactly "0.2". Other values fail with contract-mismatch. Unknown properties and enum values fail with invalid-json. Each operation is one object. Concrete examples:

// Replace text: { "op": "changeText", "target": { "paraId": "w14:...", "expect": "Acme Corp", "occurrence": 0 }, "with": "Globex Inc.", "mode": "Tracked" }

// Mark only the words that change (Word, Tracked): "granularity": "Minimal" keeps the words expect and with share at the start and end, so "thirty days" -> "forty-five days" marks only thirty -> forty-five, and "the cap" -> "125% of the cap" is a pure insertion. "Span", the default unless the connection sets one, marks the whole expect: { "op": "changeText", "target": { "paraId": "w14:...", "expect": "thirty days" }, "with": "forty-five days", "mode": "Tracked", "granularity": "Minimal" }

// Rewrite or translate a whole paragraph and keep its bold, italic, colour and links. inspect_document gives a paragraph whose words differ in formatting a markedText such as // "Payment is due within <1>30 days</1> of invoice." Keep each … around the words that should carry that formatting, wherever they land; untagged text takes the paragraph's usual formatting. // expect is the paragraph's complete text. Word and PowerPoint: { "op": "changeText", "target": { "paraId": "w14:...", "expect": "Payment is due within 30 days of invoice." }, "withMarked": "Betaling binnen <1>30 dagen</1> na factuurdatum.", "mode": "Direct" }

// Unified formatting (paragraph/run/table/row/cell/image): { "op": "format", "target": { "paraId": "w14:...", "expect": "important", "occurrence": 0 }, "highlight": "yellow", "bold": true, "color": "FF0000" } { "op": "format", "target": { "kind": "table", "path": "table#0" }, "styleId": "TableGrid", "borderStyle": "single" } { "op": "format", "target": { "kind": "image", "path": "image#0" }, "widthPx": 320, "heightPx": 200 }

// Fill / comment / insert paragraph / setProperty: { "op": "fill", "target": { "tag": "ClientName" }, "value": "Globex" } { "op": "comment", "target": { "paraId": "w14:...", "expect": "..." }, "text": "Confirm this." } { "op": "insert", "target": { "paraId": "w14:...", "expect": "..." }, "position": "After", "text": "New paragraph." } { "op": "insertParagraphs", "target": { "paraId": "w14:...", "expect": "..." }, "position": "After", "paragraphs": [{ "text": "First" }, { "text": "Second" }] } { "op": "removeParagraph", "target": { "paraId": "w14:...", "expect": "Complete paragraph text" } } { "op": "setProperty", "target": { "kind": "docProperty", "path": "core/title" }, "value": "My Title" }

// Every verb above that changes Word content also takes "mode": "Tracked" (the default - the edit lands as a redline a reviewer accepts or rejects) or "Direct". A deck refuses "Tracked": PresentationML has no revision markup.

// Review an existing redline. Revision paths come from inspect_document.nodes (kind "revision"): 'ins#7', 'del#7', 'markIns#7', 'rowIns#7', 'cellDel#7', 'runFormat#7', 'paraFormat#7'. 'all' takes every one; 'author:' takes one person's. An edit that spans a pending revision is refused with revision-overlap; resolve it here first, then re-inspect: { "op": "revision", "target": { "kind": "revision", "path": "all" }, "action": "Accept" } { "op": "revision", "target": { "kind": "revision", "path": "author:Jane Doe" }, "action": "Reject" }

// Reply to, resolve, or delete an existing comment (comment paths from inspect_document.nodes, kind "comment"): { "op": "comment", "target": { "kind": "comment", "path": "comment#1" }, "action": "Reply", "text": "Forty-five, per the MSA." } { "op": "comment", "target": { "kind": "comment", "path": "comment#1" }, "action": "Resolve" } { "op": "comment", "target": { "kind": "comment", "path": "comment#1" }, "action": "Remove" }

// Link existing text (Word only, Direct; http, https or mailto): { "op": "link", "target": { "paraId": "w14:...", "expect": "the price list" }, "url": "https://example.com/prices" } // Continue a list the document already defines (numbering id from a "list#N" node in inspect_document.nodes): { "op": "format", "target": { "paraId": "w14:...", "expect": "" }, "numberingId": 42, "listLevel": 1 }

// Use the document's own styles: styleId takes a style id or the name Word shows ("Heading 2", a template's "Body Text Blue"), as inspect_document lists them under styles. // A style the document does not define is refused with the ones it does; Normal, Heading 1-3, List Paragraph and Table Grid are added when missing, as Word adds them. Word only. { "op": "format", "target": { "paraId": "w14:...", "expect": "" }, "styleId": "Clause Heading" }

// Define a style once instead of repeating direct formatting on every paragraph. Word only. // Define it first, then apply it with format's styleId - both can sit in the same plan: { "op": "defineStyle", "styleId": "Quote", "name": "Pull Quote", "basedOn": "Normal", "next": "Normal", "fontFamily": "Georgia", "sizeHalfPoints": 24, "italic": true, "color": "444444", "alignment": "center", "indentLeftTwips": 720, "spacingBeforeTwips": 240 } { "op": "format", "target": { "paraId": "w14:...", "expect": "" }, "styleId": "Quote" } // type is paragraph (default), character or table. outlineLevel 1-9 puts a heading in the outline. // Defining a style that exists updates it; properties you leave out keep their values. Styles are // never deleted. A style cannot carry a highlight - w:highlight belongs to a run, so use color here.

// Word page geometry, breaks, and notes. All measurements are twips (1440 to the inch). Word only: { "op": "pageSetup", "paperSize": "A4", "orientation": "Landscape", "marginTopTwips": 720, "marginLeftTwips": 1080 } { "op": "insertBreak", "target": { "paraId": "w14:...", "expect": "..." }, "kind": "Page", "position": "After" } { "op": "insertBreak", "target": { "paraId": "w14:...", "expect": "..." }, "kind": "SectionNextPage" } // then pageSetup with a target inside the new section { "op": "note", "target": { "paraId": "w14:...", "expect": "thirty days" }, "kind": "Footnote", "text": "Subject to clause 8.2." } { "op": "note", "target": { "kind": "note", "path": "footnote#1" }, "action": "Update", "text": "Revised wording." } { "op": "note", "target": { "kind": "note", "path": "footnote#1" }, "action": "Remove" }

// Insert a whole new table after a paragraph, or remove an entire table (table path from inspect_document.nodes): { "op": "insertTable", "target": { "paraId": "w14:...", "expect": "..." }, "position": "After", "table": { "headers": ["Region", "Q1"], "rows": [["NL", "41850"]] } } { "op": "removeTable", "target": { "kind": "table", "path": "table#0" } }

// Add or remove table rows / columns; insert or remove image; copy or clear styles. Paths come from inspect_document.nodes: { "op": "insertTableRows", "target": { "kind": "table", "path": "table#0" }, "rows": [["NL","17","41850"]], "position": "End" } { "op": "repeatTableRow", "target": { "kind": "table", "path": "table#0" }, "templateRowIndex": 1, "records": [{ "Description": "Consulting", "Amount": "1200.00" }] } { "op": "removeTableRows", "target": { "kind": "table", "path": "table#0" }, "onlyIfEmpty": true } { "op": "mergeTableCells", "target": { "kind": "tableCell", "path": "table#0/cell#0/1" }, "columnSpan": 2 } // Word only, Direct: merges with the cells to its right { "op": "insertImage", "target": { "paraId": "w14:...", "expect": "..." }, "base64Bytes": "iVBORw0KGgo...", "imageType": "png", "widthPx": 200, "heightPx": 80 } { "op": "insertImage", "target": { "paraId": "w14:...", "expect": "..." }, "imageConnectionId": "images", "imageDocumentId": "", "imageType": "png", "widthPx": 200, "heightPx": 80 } { "op": "removeImage", "target": { "kind": "image", "path": "image#0" } } { "op": "replaceImage", "target": { "kind": "image", "path": "image#0" }, "base64Bytes": "iVBORw0KGgo...", "imageType": "png", "fit": "cover" } // keeps the frame, position and effects; fit cover (crop to fill) or contain { "op": "backgroundImage", "base64Bytes": "iVBORw0KGgo...", "imageType": "png", "opacity": 0.2 } { "op": "backgroundImage", "target": { "kind": "slide", "path": "slide#256" }, "base64Bytes": "iVBORw0KGgo...", "opacity": 0.15 } { "op": "headerFooter", "header": "Northwind Traders", "footer": "Confidential", "showPageNumber": true, "alignment": "edges", "differentFirstPage": true }

// Refresh data. fillTable replaces every cell of a table row by row, keeping cell formatting; rows must match the table's columns, and the table grows or shrinks by rows. { "op": "fillTable", "target": { "kind": "table", "path": "table#0" }, "rows": [["Region","Revenue"],["North","$1.2M"]] } // setChartData replaces any chart's data and keeps its type, colours and layout (PowerPoint; not scatter or bubble): { "op": "setChartData", "target": { "kind": "chart", "path": "chart#256/4" }, "categories": ["Jan","Feb"], "series": [{ "name": "Revenue", "values": [10,12] }] } // bindData links a Word text span or table, or a PowerPoint shape, table or chart node, to a workbook range so refresh_document can update it next time: { "op": "bindData", "target": { "paraId": "w14:...", "expect": "$4.2M" }, "source": "Summary!B2" } { "op": "bindData", "target": { "kind": "chart", "path": "chart#256/4" }, "source": "'Monthly Sales'!A1:D13" }

// Native PowerPoint chart with an editable embedded workbook: { "op": "insertChart", "target": { "kind": "slide", "path": "slide#256" }, "kind": "ClusteredColumn", "categories": ["Q1","Q2"], "series": [{ "name": "Revenue", "values": [10,12] }], "title": "Revenue", "description": "Quarterly revenue" }

// Excel cells and table rows; sheet ids and table paths come from inspection: { "op": "setCell", "target": { "sheetId": 7, "address": "B2" }, "formula": "SUM(B3:B8)" } { "op": "appendTableRows", "target": { "kind": "spreadsheetTable", "path": "table#7/Sales" }, "rows": [["APAC","15"]] }

Inputs: planJson (required), documentId (required), connectionId (required).

refresh_documentRefresh a document from a workbookA
Destructive

Update a Word report or PowerPoint deck from an Excel workbook in one call: this month's numbers, tables and charts from this month's workbook. source is the document and workbookSource the workbook, both as edit_document takes source; workbookConnectionId defaults to connectionId. The document says what to update through markers that name a workbook range, written by the bindData operation or by hand: a Word content control or PowerPoint text shape bound to one cell takes its displayed value, number format applied; a bound table is filled from its range, growing or shrinking by rows; a bound chart takes its range with the series names in the first row and the categories in the first column, and keeps its colours and layout. A range is Sheet!B2, 'Sheet name'!A1:D6, a defined name, or an Excel table name. Run with preview=true first: it lists every binding and what it will write, and saves nothing. A refresh is all or nothing - if any binding cannot be read, nothing is written and each problem is listed. saveMode and newName behave as in apply_plan; NewVersion keeps last month's document beside the new one. Returns the edit_document shape plus bindings: [{kind, marker, reference, range, target, summary, errorCode, message}].

Inputs: source (required), newName (required), preview (required), saveMode (required), +3 more.

register_documentRegister a documentA

Register an existing document with a host-configured provider connection and return its opaque documentId. source is connection-specific: for a filesystem connection, a path under its root. Never pass credentials. Returns {connectionId, documentId, name, contentType, version}.

Inputs: source (required), connectionId (required).

remove_documentRemove a document registrationA
Idempotent

Remove a document registration from a provider connection by (connectionId, documentId). Only the registration is removed - the underlying file is never deleted. Returns {removed, connectionId, documentId}.

Inputs: documentId (required), connectionId (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 16 tools

    Disambiguation3/5

    The descriptions do a good job of saying which tool to use when, but the set is built in two layers: primitives (register_document, inspect_document, find_in_document, preview_plan, apply_plan) and composites (open_document, edit_document, edit_documents, refresh_document) that redo the same work in one call. Edits have three plausible entry points (apply_plan, edit_document, edit_documents) and refresh_document overlaps apply_plan with bindData, so an agent must read carefully to choose the right one.

    Naming Consistency4/5

    Every name is snake_case verb_noun (list_documents, open_document, apply_plan, compare_documents), which is very consistent. The only friction is the minimal pair edit_document/edit_documents, where a single character separates a single-document tool from a bulk tool.

    Tool Count4/5

    Sixteen tools is on the heavy side, but the domain is broad: three document formats, connections, templates, plans, merge, compare, and workbook refresh. Each tool maps to a recognizable workflow, though the duplicate primitive/composite layers mean a few could be consolidated rather than added.

    Completeness3/5

    Read, inspect, find, edit, preview, apply, compare, merge, refresh, and template discovery are all covered, plus removal of a registration. However, create_document is repeatedly referenced by list_documents and find_templates as the consumer of a template source but is not actually present, and there is no delete/export path, leaving a dead end for new-document creation.

    Maintenance

    ActivityActive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    Appeared in Searches