# Word MCP

A Model Context Protocol (MCP) server for generating Microsoft Word documents (`.docx`) programmatically. Unlike typical MCP servers that act as gateways to APIs, this server acts as a **Factory**, converting AI-generated text and data into professional, downloadable files.

## Features

### Document Generation
- **generate_report**: Create complete Word documents in one shot
- **Markdown Support**: Automatically converts basic Markdown (bold, lists) into Word formatting
- **Rich Elements**: Supports:
    - Headers (Levels 1-3)
    - Data Tables with custom headers
    - Text Paragraphs
    - File metadata (Titles, Authors)

### Architecture
- **Local File Output**: Saves files directly to your host machine
- **Dockerized Factory**: Runs securely in a container with volume mapping
- **Stateless Operation**: No complex databases required

## Simple Setup

### 1. Local Development

1. Install dependencies:
   ```bash
   npm install
   ```

2. Create a `.env` file (Optional, defaults to `./output`):
   ```
   OUTPUT_DIR=./generated_reports
   ```

3. Build and start:
   ```bash
   npm run build
   npm start
   ```

### 2. Docker Usage

**Critical Note:** Because this server creates files, you must mount a volume to see the output.

1. Build the image:
   ```bash
   docker build -t word-mcp .
   ```

2. Run with Volume Mapping:
   ```bash
   docker run --rm -i \
     -v $(pwd)/generated_reports:/app/output \
     word-mcp
   ```

## MCP Client Integration

### Configuration for Claude Desktop

To allow the AI to save files to your Windows "Documents" folder, you must map the volume in the configuration.

1. Open your config file:
   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

2. Add this configuration:
   ```json
   {
     "mcpServers": {
       "word-mcp": {
         "command": "docker",
         "args": [
           "run",
           "--rm",
           "-i",
           "-v", "C:\\Users\\hp\\Documents\\mcp\\word-mcp\\generated_reports:/app/output",
           "word-mcp"
         ]
       }
     }
   }
   ```

   **Note:** Update the path `C:\\Users\\hp...` to match your actual project location.

### Using with Docker Compose

If you prefer docker-compose, use the included configuration:

```yaml
# docker-compose.yml
services:
  word-mcp:
    build: .
    volumes:
      - ./generated_reports:/app/output
```

## Usage Examples

### Generate a Project Audit

The AI can call the tool with structured data to create a formatted report.

```json
{
  "filename": "Audit_Report_2024",
  "title": "Q4 Security Audit",
  "sections": [
    {
      "heading": "Executive Summary",
      "content": "The audit was completed on **January 20th**. No critical vulnerabilities were found."
    },
    {
      "heading": "Vulnerability Matrix",
      "table": {
        "headers": ["Severity", "Count", "Status"],
        "rows": [
          ["High", "0", "Pass"],
          ["Medium", "2", "Investigating"]
        ]
      }
    }
  ]
}
```

## Troubleshooting

### "I can't find the generated file"
- **Check Volume Mapping:** Ensure your `claude_desktop_config.json` has the `-v` flag pointing to a valid folder on your host machine.
- **Docker Permissions:** The container runs as a non-root user (`appuser`). Ensure your host folder allows writing (usually automatic on Windows, but requires `chmod` on Linux).

### "Error: Output directory does not exist"
The server attempts to create the directory on startup. If using Docker, ensure the internal path `/app/output` is correctly mapped.

### "Formatting looks wrong"
Currently, the Markdown parser supports bold (`**text**`) and basic paragraph splitting. Complex Markdown (like code blocks or nested lists) will be rendered as plain text in this version.

## Development

Run in development mode:
```bash
npm run dev
```

Watch for changes:
```bash
npm run watch
```