mcp-docx/DEPLOYMENT.md

# docx-mcp Server - Deployment Guide

## Server Architecture

This MCP server supports:
- **stdio mode** (default): stdin/stdout for MCP clients.
- **HTTP mode**: Web interface for HTML/browser access over LAN.
- **Templates directory**: User-provided .docx templates for reuse and fill-in generation.
- **High-fidelity PDF conversion**: Via LibreOffice (included in Docker image).

```
┌─────────────────────────────────────────────────────────────────────────┐
│                        DEPLOYMENT MODES                                 │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  Mode 1: stdio (Local MCP Clients)                                      │
│  ┌───────────┐    stdio    ┌──────────────────┐                         │
│  │  MCP      │ ◄────────►  │  docx-mcp        │                         │
│  │  Client   │             │  (container)     │                         │
│  └───────────┘              └──────────────────┘                         │
│                                                                         │
│  Mode 2: HTTP (HTML Interface - LAN)                                    │
│  ┌───────────┐    HTTP:3000  ┌──────────────────┐                        │
│  │  Browser  │ ◄────────────►│  docx-mcp         │                       │
│  │  (HTML)   │               │  (container)     │                        │
│  └───────────┘                └──────────────────┘                        │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘
```

## Docker Image

There is now a single, unified Dockerfile that includes:
- HTTP server (HTML interface)
- stdio MCP transport
- LibreOffice (high-fidelity PDF conversion)
- Templates directory support
- Sandboxed, non-root configuration

Build:

```bash
docker build -t docx-mcp:full .
```

## Deployment

### HTTP Mode (HTML Interface - LAN)

Run the HTTP server with templates and output directories mounted:

```bash
docker run --rm \
    --name docx-mcp-http \
    -p 3000:3000 \
    -v /host/path/templates:/templates:ro \
    -v /host/path/output:/out \
    -e DOCX_MCP_HTTP=true \
    -e DOCX_MCP_HTTP_ADDRESS=0.0.0.0:3000 \
    -e DOCX_MCP_TEMPLATES_DIR=/templates \
    -e DOCX_MCP_MAX_SIZE=104857600 \
    -e DOCX_MCP_MAX_DOCS=30 \
    --memory 1g \
    --cpus 1.5 \
    docx-mcp:full
```

Access:
- HTML Interface: http://your-server-ip:3000
- API: http://your-server-ip:3000/api/tools
- WebSocket: ws://your-server-ip:3000/ws

### stdio Mode (for MCP Clients)

Useful when launched by an MCP client (e.g., Claude Desktop, Cursor).

```bash
docker run --rm \
    --name docx-mcp-stdio \
    -v /host/path/templates:/templates:ro \
    -v /host/path/output:/out \
    -e DOCX_MCP_TEMPLATES_DIR=/templates \
    -e DOCX_MCP_MAX_SIZE=104857600 \
    -e DOCX_MCP_MAX_DOCS=30 \
    --memory 1g \
    --cpus 1.5 \
    docx-mcp:full
```

In MCP client config, point "command" to "docker run" with these flags.

## Server Configuration

### Command Line Arguments

| Argument | Environment Variable | Description |
|----------|---------------------|-------------|
| `--http-mode` | `DOCX_MCP_HTTP=true` | Enable HTTP server mode |
| `--http-address` | `DOCX_MCP_HTTP_ADDRESS` | HTTP server address (default: 0.0.0.0:3000) |
| `--templates-dir` | `DOCX_MCP_TEMPLATES_DIR` | Directory with template .docx files (default: /templates) |
| `--readonly` | `DOCX_MCP_READONLY=true` | Enable readonly mode |
| `--sandbox` | `DOCX_MCP_SANDBOX=true` | Enable sandbox mode |
| `--no-external-tools` | `DOCX_MCP_NO_EXTERNAL_TOOLS=true` | Disable external tools (e.g., LibreOffice) |
| `--no-network` | `DOCX_MCP_NO_NETWORK=true` | Disable network operations |
| `--max-size` | `DOCX_MCP_MAX_SIZE` | Max document size in bytes |
| `--max-docs` | `DOCX_MCP_MAX_DOCS` | Max concurrent open documents |
| `--whitelist` | `DOCX_MCP_WHITELIST` | Allowed tools (comma-separated) |
| `--blacklist` | `DOCX_MCP_BLACKLIST` | Blocked tools (comma-separated) |

### Example Configurations

- HTTP mode with templates:

```bash
docker run --rm \
    -p 3000:3000 \
    -v /host/path/templates:/templates:ro \
    -e DOCX_MCP_HTTP=true \
    -e DOCX_MCP_TEMPLATES_DIR=/templates \
    docx-mcp:full
```

- Readonly HTTP mode (limited tools):

```bash
docker run --rm \
    -p 3000:3000 \
    -e DOCX_MCP_HTTP=true \
    -e DOCX_MCP_READONLY=true \
    -e DOCX_MCP_WHITELIST="list_templates,open_template,extract_text,get_metadata,search_text" \
    docx-mcp:full
```

## API Endpoints

### HTML Interface
- GET / — Web interface (tool browser + templates panel)

### REST API
- GET /api/tools — List available tools
- POST /api/call — Call a tool

### WebSocket
- WS /ws — Real-time communication

### API Examples

- List tools:

```bash
curl http://localhost:3000/api/tools
```

- Call a tool:

```bash
curl -X POST http://localhost:3000/api/call \
    -H "Content-Type: application/json" \
    -d '{
        "name": "create_document",
        "arguments": {}
    }'
```

- List templates:

```bash
curl -X POST http://localhost:3000/api/call \
    -H "Content-Type: application/json" \
    -d '{
        "name": "list_templates",
        "arguments": {}
    }'
```

- Open a template:

```bash
curl -X POST http://localhost:3000/api/call \
    -H "Content-Type: application/json" \
    -d '{
        "name": "open_template",
        "arguments": { "name": "nda_template.docx" }
    }'
```

- Generate from template with fill-in fields:

```bash
curl -X POST http://localhost:3000/api/call \
    -H "Content-Type: application/json" \
    -d '{
        "name": "generate_from_template",
        "arguments": {
          "template_name": "nda_template.docx",
          "output_path": "/out/nda_acme.docx",
          "fields": {
            "CLIENT_NAME": "Acme Corp",
            "EFFECTIVE_DATE": "2025-11-09"
          }
        }
    }'
```

## Docker Compose (Production)

Example with HTTP mode, templates, and output volumes:

```yaml
version: '3.8'

services:
  docx-mcp:
    image: docx-mcp:full
    build:
      context: .
      dockerfile: Dockerfile
    read_only: true
    cap_drop:
      - ALL
    tmpfs:
      - /tmp/docx-mcp:rw,noexec,nosuid,size=200m
    volumes:
      - ./templates:/templates:ro
      - ./output:/out
    ports:
      - "3000:3000"
    environment:
      - RUST_LOG=info
      - DOCX_MCP_HTTP=true
      - DOCX_MCP_HTTP_ADDRESS=0.0.0.0:3000
      - DOCX_MCP_TEMPLATES_DIR=/templates
      - DOCX_MCP_MAX_SIZE=104857600
      - DOCX_MCP_MAX_DOCS=30
    deploy:
      resources:
        limits:
          memory: 1G
          cpus: '1.5'
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "/usr/local/bin/docx-mcp", "--version"]
      interval: 30s
      timeout: 5s
      retries: 3
```

## Security Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `DOCX_MCP_HTTP` | `false` | Enable HTTP mode |
| `DOCX_MCP_HTTP_ADDRESS` | `0.0.0.0:3000` | HTTP server address |
| `DOCX_MCP_TEMPLATES_DIR` | `/templates` | Templates directory |
| `DOCX_MCP_READONLY` | `false` | Restrict to read-only operations |
| `DOCX_MCP_SANDBOX` | `true` | Restrict file operations to temp |
| `DOCX_MCP_NO_EXTERNAL_TOOLS` | `true` | Disable external tools |
| `DOCX_MCP_NO_NETWORK` | `true` | Disable network access |
| `DOCX_MCP_MAX_SIZE` | `104857600` | Max document size (bytes) |
| `DOCX_MCP_MAX_DOCS` | `30` | Max concurrent documents |
| `DOCX_MCP_WHITELIST` | - | Allowed tools (comma-separated) |
| `DOCX_MCP_BLACKLIST` | - | Blocked tools (comma-separated) |

### Security Profiles

- Readonly HTTP mode:

```bash
docker run --rm \
    -p 3000:3000 \
    -e DOCX_MCP_HTTP=true \
    -e DOCX_MCP_READONLY=true \
    -e DOCX_MCP_WHITELIST="list_templates,open_template,extract_text,get_metadata,search_text" \
    docx-mcp:full
```

- Maximum security:

```bash
docker run --rm \
    -p 3000:3000 \
    --read-only \
    --cap-drop ALL \
    --tmpfs /tmp/docx-mcp \
    -e DOCX_MCP_HTTP=true \
    -e DOCX_MCP_READONLY=true \
    -e DOCX_MCP_SANDBOX=true \
    -e DOCX_MCP_NO_EXTERNAL_TOOLS=true \
    -e DOCX_MCP_NO_NETWORK=true \
    docx-mcp:full
```

## Monitoring

```bash
# View logs
docker logs -f docx-mcp-http

# Check resource usage
docker stats docx-mcp-http

# Verify security
docker inspect --format='{{.HostConfig.ReadOnly}}' docx-mcp-http  # Should be true
```

## Troubleshooting

### Common Issues

1. Port already in use:
   - Use a different port:
     - -p 8080:8080 -e DOCX_MCP_HTTP_ADDRESS=0.0.0.0:8080

2. Permission denied on temp directory:
   - Ensure temp directory is writable:
     - --tmpfs /tmp/docx-mcp:rw

3. Out of memory:
   - Increase memory:
     - --memory 2g

4. CORS issues in browser:
   - CORS is enabled for all origins on LAN by default.
   - For production, restrict to specific origins as needed.

## API Key

No API key is required. Security relies on:
- OS-level access controls
- Container isolation
- Built-in command security (whitelist/blacklist)

For LAN deployments, rely on:
- Network-level access controls
- Firewall rules
- Application-level authentication at the bridge