VisualBeans

Professional document generation — Markdown to beautifully formatted DOCX/PDF.

MCP server + REST API + CLI. Open source. Built by BeansTech.

Features

• MD → DOCX: Professional quality documents via docx.js (full OOXML control)
• MD → PDF: Via Gotenberg sidecar (LibreOffice-based, high fidelity)
• Templates: ABNT Legal, Modern Clean, Corporate Formal (+ custom templates)
• Legal Design: Readability scoring (Flesch-PT), ABNT compliance, OAB advertising limits
• Visuals: SVG timelines and charts (zero dependencies)
• Quality Pipeline: Automated validation, compliance scoring, WCAG checks
• MCP Protocol: Streamable HTTP — works with Claude Code, Claude Desktop
• REST API: Standard HTTP endpoints for any integration

Quick Start

# Install
pnpm install

# Development
pnpm dev

# Run with Docker (includes Gotenberg for PDF)
docker compose -f deploy/docker-compose.yaml up

# Run tests
pnpm test

MCP Configuration

Add to your Claude Code settings:

{
  "mcpServers": {
    "visualbeans": {
      "url": "http://localhost:3201/mcp"
    }
  }
}

Available Tools (MCP)

Tool	Description
convert_md_to_docx	Markdown → DOCX with template
convert_md_to_pdf	Markdown → PDF via Gotenberg
score_readability	Flesch-PT readability analysis
validate_document	Quality + compliance checks
list_templates	Available templates
generate_timeline	SVG timeline from events
generate_chart	SVG bar/pie chart

REST API

# Convert markdown to DOCX
curl -X POST http://localhost:3201/api/convert \
  -H "Content-Type: application/json" \
  -d '{"markdown": "# Hello\n\nWorld"}' \
  -o document.docx

# Convert to PDF
curl -X POST http://localhost:3201/api/convert \
  -H "Content-Type: application/json" \
  -d '{"markdown": "# Hello", "format": "pdf"}' \
  -o document.pdf

# Score readability
curl -X POST http://localhost:3201/api/readability \
  -H "Content-Type: application/json" \
  -d '{"text": "Texto para análise."}'

Templates

ID	Description	Category
abnt-legal	Brazilian legal document (ABNT NBR 14724)	legal-br
modern-clean	Minimalist corporate design	corporate
corporate-formal	Formal business proposals	corporate

Architecture

packages/
├── core/     @visualbeans/core    — MD → DOCX engine
├── server/   @visualbeans/server  — MCP + REST server
└── cli/      @visualbeans/cli     — Local CLI tool

Deploy

Production runs on GCP Cloud Run with Gotenberg sidecar:

gcloud builds submit --config deploy/cloudbuild.yaml

License

Apache 2.0 — see LICENSE

---

Made with care by BeansTech — creators of ragjur.com.br and advogando.ai