# Project: Word MCP Server (Dockerized)
## 1. Project Goal
Build a Model Context Protocol (MCP) server that enables an LLM (Claude/Gemini) to generate high-fidelity Microsoft Word documents (`.docx`).
**Primary Use Case:** The User provides a Markdown summary or a structured report request to the Client. The Client sends this data to the MCP Server. The Server generates a `.docx` file and saves it to a local folder on the user's host machine.
## 2. Architecture & State Strategy
Unlike our previous "Gmail MCP" (which was a stateless gateway), this server is a **Factory**. It creates files.
* **Runtime:** Node.js (v20-alpine) inside Docker.
* **File Storage:** **CRITICAL:** We must use **Docker Volume Mounting**.
* The container will write files to `/app/output`.
* We must map the host directory `./generated_reports` to `/app/output`.
* If we fail to do this, the generated files will vanish when the container stops.
## 3. Tech Stack
* **Language:** TypeScript / Node.js
* **Protocol:** `@modelcontextprotocol/sdk`
* **Word Engine:** `docx` (npm package) - for programmatic document construction.
* **Validation:** `zod`
* **Deployment:** Docker + Docker Compose
## 4. API Surface (Tools)
The server will expose one primary "heavy-lifting" tool to ensure document consistency.
### Tool: `generate_report`
* **Description:** Generates a complete Word document based on a structured content payload.
* **Input Schema (Zod):**
```typescript
{
filename: string, // e.g. "audit_report" (server handles .docx extension)
title: string,
sections: [
{
heading: string,
content: string, // Markdown-supported text
},
{
heading: string,
table: {
headers: string[],
rows: string[][]
}
}
]
}
```
## 5. Implementation Roadmap (Step-by-Step)
### Step 1: Project Skeleton
* Initialize `package.json` with dependencies: `docx`, `zod`, `@modelcontextprotocol/sdk`, `dotenv`.
* Setup `tsconfig.json` (ES2022, NodeNext).
### Step 2: The Word Generator Engine (`src/word-generator.ts`)
* Create a class that accepts the JSON structure above.
* Use `docx` classes (`Document`, `Packer`, `Paragraph`, `Table`) to render the file.
* **Key Requirement:** The `save()` method must write to a configurable output path (defaulting to `./output` inside the container).
### Step 3: The MCP Server (`src/index.ts`)
* Setup the `McpServer` instance.
* Register the `generate_report` tool.
* Map the inputs to the `WordGenerator` class.
* Return a success message to the LLM: *"Report generated successfully at [Host Path]"*.
### Step 4: Docker Configuration
* **Dockerfile:** Use Node 20 Alpine. Build `dist/`. Create a non-root user.
* **docker-compose.yml:**
* Service name: `word-mcp`
* **Volume Map:** `- ./generated_reports:/app/output`
* Environment: `OUTPUT_DIR=/app/output`
## 6. Testing Plan
1. Run `npm install && npm run build`.
2. Start with `docker-compose up`.
3. Use an MCP Inspector or Claude Desktop to call `generate_report`.
4. Verify that a `.docx` file appears in the `generated_reports` folder on the host machine.
