# How OfficeCLI Processes Natural Language Commands for Document Manipulation

> Discover how OfficeCLI transforms natural language commands into structured JSON for document manipulation. Learn about its three-stage LLM pipeline and C# handlers.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: internals
- Published: 2026-07-26

---

**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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentClient.cs), while the server-side handling operates from [`src/officecli/ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs).

The LLM receives explicit instructions from the skill definition located at [`skills/officecli-word-form/SKILL.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.

```json
{
  "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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Word/WordHandler.cs) and its partial class implementations such as [`WordHandler.Add.Table.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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:

```bash
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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Help/SchemaHelpLoader.cs) | Loads Word schema and embeds utterance into template |
| 2️⃣ LLM call | [`src/officecli/ResidentClient.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentClient.cs) | Transmits prompt via MCP, receives JSON command |
| 3️⃣ Dispatch | [`src/officecli/Handlers/Rendering/HandlerRenderInput.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Rendering/HandlerRenderInput.cs) | Maps `action: "addTable"` to `WordHandler.Add.Table` |
| 4️⃣ OOXML edit | [`src/officecli/Handlers/Word/WordHandler.Add.Table.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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:

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

```

This command routes through the same core components—[`SchemaHelpLoader.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SchemaHelpLoader.cs) for prompt building, [`ResidentClient.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentClient.cs) for LLM communication, and [`HandlerRenderInput.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/HandlerRenderInput.cs) for dispatch—before reaching the PowerPoint-specific handler at [`src/officecli/Handlers/Pptx/PptxHandler.Set.Title.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Pptx/PptxHandler.Set.Title.cs).

## Key Implementation Files

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

- [`Program.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/Program.cs) – CLI entry point that parses arguments and initializes the resident server
- [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) / [`ResidentClient.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentClient.cs) – MCP protocol implementation for LLM communication
- [`SchemaHelpLoader.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SchemaHelpLoader.cs) – Schema loading and prompt template generation
- [`HandlerRenderInput.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SchemaHelpLoader.cs) component embeds document schemas into LLM prompts to constrain output validity.
- MCP protocol implementation in [`ResidentClient.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentClient.cs) and [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) handles communication with OpenAI GPT-4-Turbo.
- JSON command objects route through [`HandlerRenderInput.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/HandlerRenderInput.cs) to strongly-typed handlers like [`WordHandler.Add.Table.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentClient.cs) (client) and [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Word/WordHandler.cs) and its partial files (e.g., [`WordHandler.Add.Table.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.Add.Table.cs)), while PowerPoint handlers follow a similar pattern in the `Pptx` subdirectory. A generic dispatcher in [`HandlerRenderInput.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/HandlerRenderInput.cs) routes JSON commands to these implementations based on the `action` field.