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
@@ -5,6 +5,7 @@ A comprehensive Model Context Protocol (MCP) server for Microsoft Word DOCX file
 ## 📖 Table of Contents

 - [Quick Start](#-quick-start)
+- [Transport Modes](#-transport-modes)
 - [AI Tool Integration](#-ai-tool-integration)
  - [Claude Desktop](#claude-desktop)
  - [Cursor](#cursor)
@@ -58,6 +59,7 @@ The server will automatically use external tools if available for enhanced quali
 The server includes comprehensive security features for enterprise and restricted environments:

 ### Readonly Mode
+
 ```bash
 # Enable readonly mode - only allows document viewing and analysis

@@ -77,6 +79,7 @@ In readonly mode, only these operations are allowed:
 - Get document metadata and statistics

 ### Command Filtering
+
 ```bash
 # Whitelist specific commands only

@@ -96,6 +99,7 @@ export DOCX_MCP_BLACKLIST="save_document,convert_to_pdf,merge_documents"
 ```

 ### Sandbox Mode
+
 ```bash
 # Restrict all file operations to temp directory only

@@ -108,6 +112,7 @@ export DOCX_MCP_SANDBOX=true
 ```

 ### Resource Limits
+
 ```bash
 # Set maximum document size (100MB default)

@@ -126,6 +131,37 @@ export DOCX_MCP_NO_NETWORK=true
  --no-network
 ```

+## 🌐 Transport Modes
+
+The server supports two transport modes:
+
+- **stdio (default)**:
+  - Communicates over stdin/stdout.
+  - Ideal for MCP clients (Claude Desktop, Cursor, etc.).
+
+- **HTTP (for HTML/browser access over LAN)**:
+  - Provides:
+    - A web interface for browsing and using tools.
+    - A REST API for programmatic access.
+    - A WebSocket endpoint for real-time communication.
+
+To enable HTTP mode:
+
+```bash
+# Using command line
+./target/release/docx-mcp --http-mode --http-address 0.0.0.0:3000
+
+# Using environment variables
+export DOCX_MCP_HTTP=true
+export DOCX_MCP_HTTP_ADDRESS=0.0.0.0:3000
+./target/release/docx-mcp
+```
+
+Access:
+- HTML Interface: http://your-server-ip:3000
+- API: http://your-server-ip:3000/api/tools
+- WebSocket: ws://your-server-ip:3000/ws
+
 ## 🤖 AI Tool Integration

 ### Claude Desktop
@@ -150,6 +186,7 @@ Add to your Claude Desktop configuration file:
 ```

 **With Security Options (using command-line arguments):**
+
 ```json
 {
  "mcpServers": {
@@ -165,6 +202,7 @@ Add to your Claude Desktop configuration file:
 ```

 **With Security Options (using environment variables):**
+
 ```json
 {
  "mcpServers": {
@@ -193,6 +231,7 @@ After adding, restart Claude Desktop. You can then ask Claude to:
 Add to your Cursor settings (`~/.cursor/config.json` or through Settings UI):

 **Basic Configuration:**
+
 ```json
 {
  "mcp": {
@@ -210,6 +249,7 @@ Add to your Cursor settings (`~/.cursor/config.json` or through Settings UI):
 ```

 **With Security Options (using command-line arguments):**
+
 ```json
 {
  "mcp": {
@@ -227,6 +267,7 @@ Add to your Cursor settings (`~/.cursor/config.json` or through Settings UI):
 ```

 **With Security Options (using environment variables):**
+
 ```json
 {
  "mcp": {
@@ -250,6 +291,7 @@ Add to your Cursor settings (`~/.cursor/config.json` or through Settings UI):
 Add to your Windsurf configuration (`~/.windsurf/config.json`):

 **Basic Configuration:**
+
 ```json
 {
  "mcp": {
@@ -267,6 +309,7 @@ Add to your Windsurf configuration (`~/.windsurf/config.json`):
 ```

 **With Security Options (using arguments):**
+
 ```json
 {
  "mcp": {
@@ -288,6 +331,7 @@ Add to your Windsurf configuration (`~/.windsurf/config.json`):
 Add to your Continue configuration (`~/.continue/config.json`):

 **Basic Configuration:**
+
 ```json
 {
  "models": [
@@ -306,6 +350,7 @@ Add to your Continue configuration (`~/.continue/config.json`):
 ```

 **With Security Options:**
+
 ```json
 {
  "models": [
@@ -328,6 +373,7 @@ Add to your Continue configuration (`~/.continue/config.json`):
 If using the MCP extension for VS Code, add to your workspace settings (`.vscode/settings.json`):

 **Basic Configuration:**
+
 ```json
 {
  "mcp.servers": {
@@ -343,6 +389,7 @@ If using the MCP extension for VS Code, add to your workspace settings (`.vscode
 ```

 **With Security Options:**
+
 ```json
 {
  "mcp.servers": {
@@ -369,6 +416,9 @@ docx-mcp --help

 | Argument | Environment Variable | Description | Example |
 |----------|---------------------|-------------|---------|
+| `--http-mode` | `DOCX_MCP_HTTP=true` | Enable HTTP server mode (HTML interface) | `--http-mode` |
+| `--http-address` | `DOCX_MCP_HTTP_ADDRESS` | HTTP server address (default: 0.0.0.0:3000) | `--http-address 0.0.0.0:3000` |
+| `--templates-dir` | `DOCX_MCP_TEMPLATES_DIR` | Directory with template .docx files (default: /templates) | `--templates-dir /path/to/templates` |
 | `--readonly` | `DOCX_MCP_READONLY=true` | Enable readonly mode - only viewing operations | `--readonly` |
 | `--whitelist <COMMANDS>` | `DOCX_MCP_WHITELIST` | Comma-separated list of allowed commands | `--whitelist open_document,extract_text` |
 | `--blacklist <COMMANDS>` | `DOCX_MCP_BLACKLIST` | Comma-separated list of forbidden commands | `--blacklist save_document,convert_to_pdf` |
@@ -383,9 +433,12 @@ docx-mcp --help
 ### Example Usage

 ```bash
-# Basic usage
+# Basic usage (stdio mode)
 ./target/release/docx-mcp

+# HTTP mode for HTML interface
+./target/release/docx-mcp --http-mode --http-address 0.0.0.0:3000
+
 # Readonly mode with size limit
 ./target/release/docx-mcp --readonly --max-size 10485760

@@ -428,6 +481,37 @@ docx-mcp --help
 - **Multiple Documents**: Handle multiple documents simultaneously
 - **Temp File Management**: Automatic cleanup of temporary files

+### Templates and Fill-in Generation
+
+The server supports a templates directory for reusable document templates:
+
+- **Templates directory**:
+  - Configurable via `--templates-dir` or `DOCX_MCP_TEMPLATES_DIR`.
+  - Intended to be mounted in Docker (e.g., `/templates`).
+- **Template tools**:
+  - `list_templates`: Lists all `.docx` templates available.
+  - `open_template`: Opens a template by name as a working document.
+  - `generate_from_template`: Generates a new document from a template with fill-in fields.
+- **Fill-in fields**:
+  - Use placeholders like `{{CLIENT_NAME}}` in your template.
+  - Provide field values as key-value pairs when calling `generate_from_template`.
+
+Example:
+
+```json
+{
+  "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"
+    }
+  }
+}
+```
+
 ### Professional Templates
 - **Business Letters**: Professional correspondence with proper formatting
 - **Resumes**: Modern resume layouts with sections for experience, education, skills
@@ -664,6 +748,46 @@ Saves the document to a specified path.
 }
 ```

+### Template Tools
+
+#### `list_templates`
+Lists all available templates in the configured templates directory.
+```json
+{
+  "tool": "list_templates",
+  "arguments": {}
+}
+```
+
+#### `open_template`
+Opens a template document by name from the templates directory.
+```json
+{
+  "tool": "open_template",
+  "arguments": {
+    "name": "nda_template.docx"
+  }
+}
+```
+
+#### `generate_from_template`
+Generates a new document from a template by filling placeholders like `{{FIELD_NAME}}` with provided values.
+
+Example:
+```json
+{
+  "tool": "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"
+    }
+  }
+}
+```
+
 ### Content Addition

 #### `add_paragraph`
@@ -784,6 +908,7 @@ Finds and replaces text in the document.
 ## Example Workflows

 ### Creating a Report
+
 ```javascript
 // 1. Create a new document
 const doc = await mcp.call("create_document", {});
@@ -820,6 +945,7 @@ await mcp.call("convert_to_pdf", {
 ```

 ### Batch Processing Documents
+
 ```javascript
 // Open and convert multiple documents
 const documents = ["doc1.docx", "doc2.docx", "doc3.docx"];
@@ -850,6 +976,23 @@ for (const docPath of documents) {
 }
 ```

+### Using Templates
+
+```javascript
+// 1. List available templates
+const templates = await mcp.call("list_templates", {});
+
+// 2. Generate a new document from a template with fill-in fields
+const result = await mcp.call("generate_from_template", {
+  template_name: "nda_template.docx",
+  output_path: "/out/nda_acme.docx",
+  fields: {
+    "CLIENT_NAME": "Acme Corp",
+    "EFFECTIVE_DATE": "2025-11-09"
+  }
+});
+```
+
 ## Architecture

 The server is built with a modular architecture:
@@ -858,20 +1001,24 @@ The server is built with a modular architecture:
 - **`docx_handler.rs`**: Core DOCX manipulation logic
 - **`converter.rs`**: PDF and image conversion functionality
 - **`docx_tools.rs`**: MCP tool definitions and handlers
+- **`http_server.rs`**: HTTP server and HTML interface for LAN access

 ## Development

 ### Building from Source
+
 ```bash
 cargo build
 ```

 ### Running Tests
+
 ```bash
 cargo test
 ```

 ### Debug Mode
+
 ```bash
 RUST_LOG=debug cargo run
 ```
@@ -1045,4 +1192,4 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 - Built with the official [MCP Rust SDK](https://github.com/modelcontextprotocol/rust-sdk)
 - Uses [docx-rs](https://github.com/bokuweb/docx-rs) for DOCX manipulation
 - PDF generation with [printpdf](https://github.com/fschutt/printpdf)
- Image processing with [image-rs](https://github.com/image-rs/image)
+- Image processing with [image-rs](https://github.com/image-rs/image)