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:

docker build -t docx-mcp:full .

Deployment

HTTP Mode (HTML Interface - LAN)

Run the HTTP server with templates and output directories mounted:

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).

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:

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):

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:

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

• Call a tool:

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

• List templates:

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

• Open a template:

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:

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:

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:

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:

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

# 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