Report Writer MCP
Relevant source files
The following files were used as context for generating this wiki page:
The Report Writer MCP is an automated report generation system designed to produce structured investigation reports, technical documentation, and compliance summaries from research findings. Operating as a specialized server within the Engineering Platform's Model Context Protocol (MCP) ecosystem, it enables AI agents to generate court-ready or executive-level documents in multiple formats, including Markdown, PDF, and DOCX.
This system serves as the final stage in the "Adaptive Research Engine" pipeline, transforming raw data processed by other servers—such as research-swarm and basin-analyzer—into human-readable, formatted outputs with quality scoring.
Sources: mcp-servers/report-writer/server.py:16-33, mcp-servers/README.md:129-132, README.md:99-105
System Architecture
The Report Writer MCP implements a standard MCP SSE (Server-Sent Events) transport protocol (version 2024-11-05). It consists of an HTTP+SSE server that manages active sessions and routes JSON-RPC requests to specialized tool handlers.
Core Components
- Transport Layer: Handles GET
/ssefor establishing connections and POST/sse(or/messages) for receiving JSON-RPC tool calls. - Tool Dispatcher: A mapping layer that routes incoming MCP methods (like
tools/call) to asynchronous Python functions. - Report Storage: An in-memory dictionary-based storage system (
REPORTS) that tracks report metadata, sections, findings, and citations. - Export Engine: A multi-format generator utilizing libraries like
pandoc(via subprocess) for PDF generation andpython-docxfor Word documents.
Sources: mcp-servers/report-writer/server.py:35-46, mcp-servers/report-writer/server.py:358-375, mcp-servers/README.md:179-183
Data Flow Diagram
The following diagram illustrates the lifecycle of a report, from initial creation via MCP tools to final multi-format export.
The diagram shows the transition from raw JSON-RPC calls to processed file artifacts stored on the local filesystem.
Sources: mcp-servers/report-writer/server.py:43-52, mcp-servers/report-writer/server.py:228-300
MCP Toolset
The server exposes a comprehensive suite of tools for granular report construction. This allows AI agents to build reports iteratively by adding sections, evidence, and contradictions.
Investigation & Content Tools
| Tool Name | Purpose | Key Parameters |
|---|---|---|
create_report | Initializes a new report object | case_id, report_type, title |
add_section | Adds a header and content block | report_id, heading, content, level |
add_finding | Logs a specific investigation result | finding, sources, confidence |
add_contradiction | Documents conflicting evidence | source1, source2, severity |
add_brady_item | Documents exculpatory material | item_type, priority, sources |
add_timeline_event | Adds a dated event to the timeline | date, event, actors, source |
Sources: mcp-servers/report-writer/server.py:56-146
Export & Status Tools
| Tool Name | Description | Output |
|---|---|---|
export_markdown | Saves report as a .md file | File path and byte size |
export_pdf | Converts markdown to PDF via Pandoc | File path or fallback error |
export_docx | Generates a Word document | File path via python-docx |
get_report_status | Returns counts of findings/sections | Summary text |
list_reports | Lists all reports for a specific case | Formatted list of IDs/Titles |
Sources: mcp-servers/report-writer/server.py:147-196
Data Model & Schema
Each report is stored as a complex object. The internal structure is designed to support legal and technical rigor, including confidence levels and source citations.
The entity-relationship diagram represents the hierarchical structure of the report object used for markdown synthesis.
Sources: mcp-servers/report-writer/server.py:204-225
Export Implementation Details
The Report Writer MCP uses a "Markdown-First" strategy. All exports begin with the internal _generate_markdown function, which synthesizes the diverse entities (findings, timeline, etc.) into a cohesive document.
PDF and DOCX Generation
- PDF: The system attempts to use
pandocwith axelatexengine. Ifpandocis not found, the system provides a graceful fallback by saving the markdown version and reporting a configuration error. - DOCX: Utilizes the
python-docxlibrary to programmatically build the document structure, applying bold styles to confidence markers and priorities.
Sources: mcp-servers/report-writer/server.py:303-345, mcp-servers/README.md:144-150
Code Snippet: Markdown Synthesis Logic
The following logic demonstrates how confidence scores and severity are visualized using icons in the final document.
# Sources: [mcp-servers/report-writer/server.py:255-261](https://github.com/Bbadhub/eng-platform/blob/HEAD/mcp-servers/report-writer/server.py#L255-L261)
# Findings visualization in _generate_markdown
if report.get("findings"):
md.append("## Key Findings\n")
for i, finding in enumerate(report["findings"], 1):
confidence_icon = {"HIGH": "🔴", "MEDIUM": "🟡", "LOW": "🟢"}.get(finding["confidence"], "⚪")
md.append(f"{i}. {confidence_icon} **{finding['confidence']}** - {finding['finding']}")
Configuration and Deployment
The server is configured via environment variables, allowing it to be deployed in various environments (local, Docker, or SaaS).
| Variable | Description | Default |
|---|---|---|
MCP_SERVER_PORT | The port the HTTP server listens on | 3015 |
REPORTS_OUTPUT_DIR | Filesystem path for exported files | /data/reports |
MCP_AUTH_TOKEN | Bearer token for API security | "" (Open) |
TEMPLATES_DIR | Path to Markdown report templates | /templates |
Sources: mcp-servers/report-writer/server.py:38-41, mcp-servers/README.md:146-150, mcp-servers/mcp-saas-template/template/site/index.html:132-145
Integration with Engineering Platform
The Report Writer MCP is recognized as a "Core AI Enhancement Server" within the broader platform. It is typically integrated as a git submodule and used in conjunction with task management tools.
- Sync Strategy: Integrated into projects via
.mcp.jsonconfiguration pointing to the submodule location. - Workflow: AI agents utilize the
report-writerto document the results of automated audits, regression tests, or DORA metrics collection. - Authentication: Supports Bearer token and API key authentication via headers or query parameters for secure remote access.
Sources: PROMPT-ADD-TO-EXISTING.md:43-52, README.md:112-115, mcp-servers/report-writer/server.py:408-420
Summary
The Report Writer MCP provides a standardized, iterative interface for document generation. By abstracting the complexities of LaTeX and Word document formatting into simple JSON-RPC tool calls, it enables consistent, high-quality documentation for investigations and engineering audits within the Engineering Platform ecosystem.