Professional Template-Based Report Generator

This demo shows how to generate professional Word template-based reports from any structured data. Transform your JSON data into polished DOCX or PDF reports using customizable Word templates.

Key Features:

Generic Report Generation: Generate reports from any template and data structure - not limited to specific use cases
Dynamic Data & Templates: Combine structured JSON data with customizable Word templates to generate professional reports
MCP Server Integration: Built-in Model Context Protocol (MCP) server enables AI agents and IDEs (like Cursor, Claude Desktop) to generate reports programmatically
Test Web UI: Interactive web interface at /ui/reports for testing template uploads and report generation without writing code
Multiple Output Formats: Generate reports as DOCX or PDF with a single API call
Template Management: Upload and manage templates dynamically
Data Validation: Validate report data against template schemas
HTML Rendering: Configurable HTML rendering for specific fields
Document Options: Read-only protection, draft watermarks, field updates

Example Use Case: This repository includes a Statement of Applicability (SoA) report for ISO 27001 as a working example, demonstrating the capabilities with a real-world scenario.

IMPORTANT: The example data was generated with AI/GPT tools and is not a real-world example.

Related blog post: https://m2x.rocks/poi-tl-professionelle-berichte-aus-word-templates/

Table of Contents:

Usage
Screenshots
Developer Documentation

Usage

Run the MCP server with docker compose as described below.

Note: this service is intended for demo and development purposes only. For production use, please adapt the configuration and security settings accordingly.

Get the compose.yml file and run it:

curl -L -o compose.yml https://raw.githubusercontent.com/mmrotzek/demo-professional-docx-pdf-report-poi-tl/refs/heads/main/compose.prod.yml

 docker compose up -d

This starts the MCP server on port 8080 - http://localhost:8080/mcp/message (MCP Streamable HTTP: JSON-RPC over HTTP with optional streaming responses) - and docx2pdf conversion service on port 7700.
You can test the report generation service using the built-in Web UI: http://localhost:8080/ui/reports - a HTML interface for generating dynamic reports with template upload and JSON data input.

This application includes an MCP (Model Context Protocol) server that enables AI agents (like Claude, GPT, or Cursor IDE) to generate professional DOCX/PDF reports using custom templates and structured data.

Templates are located in src/main/resources/templates.

Example: Configure MCP Server for Cursor IDE

When server is running on localhost:8080:

Option 1: Project-specific configuration (recommended)
- Copy .cursor/mcp.json.example to .cursor/mcp.json in this project
- Or create .cursor/mcp.json with the configuration below
Option 2: Global configuration
- Create or update ~/.cursor/mcp.json on your system

Configuration content:

{
  "mcpServers": {
    "document-report-generator": {
      "url": "http://localhost:8080/mcp/message",
      "transport": "streamableHttp"
    }
  }
}

Important:

Make sure the application is running on localhost:8080 before connecting
After adding the configuration, restart Cursor IDE
The MCP server tools (generate_report, provide_template, validate_data, list_templates) will be available in Cursor's AI chat

Note: The server uses Streamable HTTP transport which is compatible with Cursor IDE.

Screenshots

Portrait

Word Template - src/main/resources/templates/template.docx

Front Page	Other Pages

Rendered as DOCX - Full document: example/portrait.docx

Rendered as PDF - Full report: example/portrait.pdf

Landscape

Word Template - src/main/resources/templates/template_table.docx

Front Page	Other Pages

Rendered as DOCX - Full document: example/landscape.docx

Rendered as PDF - Full report: example/landscape.pdf

Developer Documentation

Want to try yourself?! - Out of the Box Demo

This is a Spring Boot application that uses poi-tl for Word document generation and moalhaddar/docx-to-pdf for PDF conversion via REST API.

Requirements

Docker is required for PDF conversion.

Run

docker compose up -d

./mvnw spring-boot:run - or run the DemoApplication class in IDEA (requires Lombok enabled).

Usage

Web UI: http://localhost:8080/ui/reports - HTML interface for generating dynamic reports with template upload and JSON data input.

Templates are located in src/main/resources/templates.

Template Placeholders in Word Documents

Creating templates is simple - just open Microsoft Word and type placeholders using double curly braces:

Simple values: {{customerName}}, {{price}}, {{date}}
Nested objects: {{customer.name}}, {{customer.address.city}}
Lists/Tables: {{?items}}{{description}}{{/items}} (loops iterate over array items)

That's it! Save as .docx and use it to generate reports.

Advanced: To render HTML content (bold, italic, lists, etc.), specify fields in the htmlFields option with HTML tags: , , , , <ul>, <ol>, <li>,  .

MCP

Configuration

MCP server settings in application.properties:

m2x.demo.mcp.enabled=true
m2x.demo.mcp.stdio-enabled=true
m2x.demo.mcp.http-enabled=true
m2x.demo.mcp.http-path=/mcp/message
m2x.demo.mcp.max-template-size=10485760
m2x.demo.mcp.template-ttl=PT1H

# Spring AI MCP Server Configuration
spring.ai.mcp.server.enabled=true
spring.ai.mcp.server.type=SYNC
spring.ai.mcp.server.protocol=STREAMABLE
spring.ai.mcp.server.annotation-scanner.enabled=true
# Streamable HTTP endpoint configuration
spring.ai.mcp.server.streamable-http.mcp-endpoint=/mcp/message

MCP Tools

The MCP server provides the following tools for AI agents:

`generate_report`

Generate DOCX/PDF reports from structured data and templates.

Parameters:

templateId (optional): Template identifier or path (e.g., "template_soa.docx")
templateContent (optional): Base64 encoded .docx template (for dynamic templates)
reportData (required): JSON object matching template placeholders
outputFormat (optional): "docx" or "pdf" (default: "docx")
options (optional): Report options object:
- readonly (boolean): Enable read-only protection
- draft (boolean): Add draft watermark
- htmlFields (string): Comma-separated list of fields to render as HTML

Returns: Base64 encoded document

`provide_template`

Upload and register a template for later use in report generation.

Parameters:

templateName (required): Unique template identifier (will be used as templateId)
templateContent (required): Base64 encoded .docx file
description (optional): Human-readable template description

Returns: Template registration confirmation with templateId

`validate_data`

Validate report data against template requirements before generation.

Parameters:

templateId (required): Template identifier to validate against
reportData (required): JSON object to validate

Returns: Validation result with any errors or warnings

`list_templates`

Get list of available templates with metadata.

Returns: Array of template objects with id, name, description, and size information

Resources

template://schema/{templateId} - JSON Schema defining expected data structure
template://info/{templateId} - Template metadata (name, description, version)
sample://data/{templateId} - Example data structure for a template

Security Considerations

Apache POI Zip Security: Configured limits to prevent zip-bomb attacks:
- Minimum inflate ratio: 1% (prevents highly compressed files from expanding to huge sizes)
- Maximum entry size: 100MB per ZIP entry
- Maximum text size: 50MB for extracted text
Template Content Validation: Validates .docx files have proper ZIP signature to prevent malicious files
File Size Limits: Base64 template content limited to 10MB (configurable via m2x.demo.mcp.max-template-size)
Temporary File Cleanup: Automatic cleanup with configurable TTL (default: 1 hour via m2x.demo.mcp.template-ttl)
Path Traversal Protection:
- Template names validated to reject path separators, traversal sequences (..), and absolute paths
- Server-generated UUIDs used for template IDs (never user input)
- Canonical path validation ensures files stay within designated directories
- Classpath template allowlist prevents arbitrary resource loading

Name		Name	Last commit message	Last commit date
.cursor		.cursor
.github/workflows		.github/workflows
.mvn/wrapper		.mvn/wrapper
etc/owasp		etc/owasp
example		example
src		src
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
compose.prod.yml		compose.prod.yml
compose.yml		compose.yml
mcp_test_curl.md		mcp_test_curl.md
mvnw		mvnw
mvnw.cmd		mvnw.cmd
pom.xml		pom.xml

Navigation Menu

Repository files navigation

Professional Template-Based Report Generator

Usage

Example: Configure MCP Server for Cursor IDE

Screenshots

Portrait

Landscape

Developer Documentation

Want to try yourself?! - Out of the Box Demo

Requirements

Run

Usage

Template Placeholders in Word Documents

MCP

Configuration

MCP Tools

`generate_report`

`provide_template`

`validate_data`

`list_templates`

Resources

Security Considerations

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Professional Template-Based Report Generator

Usage

Example: Configure MCP Server for Cursor IDE

Screenshots

Portrait

Landscape

Developer Documentation

Want to try yourself?! - Out of the Box Demo

Requirements

Run

Usage

Template Placeholders in Word Documents

MCP

Configuration

MCP Tools

generate_report

provide_template

validate_data

list_templates

Resources

Security Considerations

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`generate_report`

`provide_template`

`validate_data`

`list_templates`