How OfficeCLI Processes Natural Language Commands for Document Manipulation

OfficeCLI converts free-form natural language instructions into structured JSON commands using a three-stage LLM pipeline, then dispatches them to strongly-typed C# handlers that manipulate OOXML documents directly.

The iOfficeAI/OfficeCLI repository provides a command-line interface that bridges human language and Microsoft Office document manipulation. By processing natural language commands through a structured pipeline, the tool translates utterances like "Add a table with three columns" into precise OOXML operations without requiring users to learn complex APIs.

The Three-Stage Natural Language Processing Pipeline

OfficeCLI implements a strict separation between language understanding and document manipulation. The architecture routes user input through three distinct phases to ensure reliable execution.

Stage 1: Prompt Generation with Schema Context

The pipeline begins in src/officecli/Help/SchemaHelpLoader.cs, where the CLI constructs a context-rich prompt that embeds the user's natural language utterance alongside the target document schema.

This component loads JSON schema definitions for specific Office types—Word, Excel, or PowerPoint—and injects the schema constraints into a predefined template. By providing the LLM with structural context upfront, the system ensures the generated commands remain valid for the target document format.

Stage 2: LLM Inference via MCP Protocol

The generated prompt travels to the configured LLM—OpenAI GPT-4-Turbo by default—through the Model Control Protocol (MCP) implementation. The client-side request logic resides in src/officecli/ResidentClient.cs, while the server-side handling operates from src/officecli/ResidentServer.cs.

The LLM receives explicit instructions from the skill definition located at skills/officecli-word-form/SKILL.md, which directs the model to return a strictly formatted JSON command object. This JSON must conform to the schema loaded in Stage 1 and includes an action field that specifies the operation type.

{
  "action": "addTable",
  "target": "body",
  "properties": {
    "columns": 3,
    "header": true
  }
}

The MCP protocol ensures reliable serialization and transport of these structured responses back to the CLI process.

Stage 3: Command Dispatch and OOXML Execution

Upon receiving the JSON response, src/officecli/Handlers/Rendering/HandlerRenderInput.cs deserializes the payload and routes the command based on the action field value. This generic dispatcher maps action strings to concrete handler methods.

For Word documents, execution flows to src/officecli/Handlers/Word/WordHandler.cs and its partial class implementations such as WordHandler.Add.Table.cs. These handlers contain low-level OOXML manipulation code that creates, updates, or removes document parts according to the JSON properties. The strongly-typed C# implementation ensures type safety while performing direct XML element manipulation.

End-to-End Command Examples

Example 1: Adding a Table in Word

The following command demonstrates the complete flow from natural language to OOXML insertion:

officecli word "Add a table with 4 columns and a header row"

The internal processing follows this sequence:

Step	Source File	Function
1️⃣ Prompt creation	src/officecli/Help/SchemaHelpLoader.cs	Loads Word schema and embeds utterance into template
2️⃣ LLM call	src/officecli/ResidentClient.cs	Transmits prompt via MCP, receives JSON command
3️⃣ Dispatch	src/officecli/Handlers/Rendering/HandlerRenderInput.cs	Maps action: "addTable" to WordHandler.Add.Table
4️⃣ OOXML edit	src/officecli/Handlers/Word/WordHandler.Add.Table.cs	Generates <w:tbl> element with specified columns and header

Example 2: Updating PowerPoint Slide Titles

The pipeline supports multiple Office formats through specialized handlers:

officecli pptx "Rename the title of slide 2 to 'Quarterly Results'"

This command routes through the same core components—SchemaHelpLoader.cs for prompt building, ResidentClient.cs for LLM communication, and HandlerRenderInput.cs for dispatch—before reaching the PowerPoint-specific handler at src/officecli/Handlers/Pptx/PptxHandler.Set.Title.cs.

Key Implementation Files

The architecture relies on specific source files that manage distinct responsibilities:

• Program.cs – CLI entry point that parses arguments and initializes the resident server
• ResidentServer.cs / ResidentClient.cs – MCP protocol implementation for LLM communication
• SchemaHelpLoader.cs – Schema loading and prompt template generation
• HandlerRenderInput.cs – Generic dispatcher routing JSON actions to typed handlers
• WordHandler.*.cs – Concrete Word manipulation implementations (tables, styles, formatting)
• skills/officecli-word-form/SKILL.md – LLM skill definition and schema documentation

Summary

• OfficeCLI processes natural language commands through a three-stage pipeline: prompt generation, LLM inference, and handler dispatch.
• The SchemaHelpLoader.cs component embeds document schemas into LLM prompts to constrain output validity.
• MCP protocol implementation in ResidentClient.cs and ResidentServer.cs handles communication with OpenAI GPT-4-Turbo.
• JSON command objects route through HandlerRenderInput.cs to strongly-typed handlers like WordHandler.Add.Table.cs.
• Direct OOXML manipulation occurs in specialized handler classes, ensuring precise document modifications.

Frequently Asked Questions

What LLM does OfficeCLI use by default?

OfficeCLI defaults to OpenAI GPT-4-Turbo for natural language processing. The LLM client configuration resides in src/officecli/ResidentClient.cs, which implements the Model Control Protocol (MCP) to standardize request handling and response parsing.

How does OfficeCLI ensure generated commands match document schemas?

The system enforces schema conformity through src/officecli/Help/SchemaHelpLoader.cs, which injects JSON schema definitions directly into the LLM prompt. Additionally, the skill definition in skills/officecli-word-form/SKILL.md explicitly instructs the model to return commands that validate against these schemas, reducing hallucination and structural errors.

What is the MCP protocol used for in OfficeCLI?

The Model Control Protocol (MCP) provides the communication layer between the CLI and the LLM. Implemented across ResidentClient.cs (client) and ResidentServer.cs (server), MCP handles prompt transport, response streaming, and JSON deserialization, ensuring reliable command generation even for complex document operations.

Where are the document manipulation handlers implemented?

Concrete handlers reside in the src/officecli/Handlers/ directory. Word-specific logic is in src/officecli/Handlers/Word/WordHandler.cs and its partial files (e.g., WordHandler.Add.Table.cs), while PowerPoint handlers follow a similar pattern in the Pptx subdirectory. A generic dispatcher in HandlerRenderInput.cs routes JSON commands to these implementations based on the action field.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}