Add HTTP interface, templates, generate_from_template, unified Dockerfile

2026-06-13 00:22:02 +00:00
parent d3fbbcfd7c
commit f655336757
11 changed files with 1789 additions and 45 deletions
@@ -0,0 +1,338 @@
+# 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