Il DOCX prodotto dalla versione precedente emetteva i div Tielogic
(`<div class="cover">`, `<div class="info-col">`, `<div class="acceptance">`,
`<div class="status-card">`) come testo grezzo: Pandoc non sa
interpretare il CSS-flavoured HTML del PDF e li copia letteralmente
nel documento Word. Anche le tabelle `<table class="financial">`
finivano spezzate cella per cella.
Il fix introduce un preprocessor dedicato che riscrive tutta la
HTML Tielogic-flavoured in Markdown nativo prima di passare il
documento a Pandoc.
- docx_preprocessor.py: nuovo modulo basato su BeautifulSoup. Strippa
frontmatter e <style>, poi rewrite di:
* <div class="cover"> → titoli H1/H2, paragrafi, tabella pipe
2-col FORNITORE/CLIENTE, validità in italic, \newpage finale
* <table class="financial"> → tabella pipe Markdown con riga
total-row in **bold**
* <div class="acceptance"> → heading H2 + intro + tabella pipe
con riga firma `_____________________` + luogo/data
* <div class="status-card"> → paragrafo "**name** — descrizione"
* <span class="badge ..."> → testo **bold**
* <div class="page-break"> → \newpage Pandoc-friendly
- docx_renderer.py: deferisce tutto il preprocessing al nuovo modulo
(più compatto, niente regex sparse).
- pyproject.toml + uv.lock: aggiunta dipendenza beautifulsoup4>=4.12.
- 8 nuovi test unit per il preprocessor (cover, tabelle, badge,
acceptance, idempotenza, niente div residui, badge standalone).
Adattati i test esistenti agli import dal nuovo modulo. 101 verde.
Smoke E2E via MCP: l'offerta TieMeasureFlow esce in DOCX leggibile
con tabelle Word native, heading colorati Tielogic e firme in tabella.
Aggiunge la generazione di documenti Word coerenti con l'identità
visiva Tielogic, in parallelo al render PDF già esistente. Il flusso
completo è ora `bullet input → Markdown formattato → PDF e/o DOCX`
in una singola chiamata MCP.
- docx_renderer.py: subprocess Pandoc che legge il Markdown da stdin,
emette il binario .docx su stdout. Strippa il YAML frontmatter e i
blocchi `<style>` (presenti per il PDF, irrilevanti in DOCX) prima
della conversione.
- mcp_tools.py: nuovo tool `document_to_docx(markdown)` che ritorna
`{docx_b64, size_bytes}`; `document_generate` esteso con
`output_format ∈ {md, pdf, docx, all}`. La firma di
`build_mcp_server` accetta ora `docx_reference_path` opzionale.
- config.py: `Settings.docx_reference_path` (default
/app/themes/tielogic-reference.docx).
- main.py: passa la nuova setting a `build_mcp_server`.
- mcp-docugen.Dockerfile: installazione di pandoc accanto alle libs
Chromium.
- themes/tielogic-reference.docx: reference Word (10 KB) con stili
Tielogic — heading colors blu/dark, font Inter, dimensioni allineate
al CSS web. Generato da `scripts/build-reference-docx.py` che parte
dal reference.docx di default di Pandoc e riscrive `word/styles.xml`
con regex sui blocchi `<w:style>`. Pandoc lo applica in automatico
agli output DOCX prodotti dal servizio.
- 9 nuovi test unit per docx_renderer (strip frontmatter/style,
preprocess combinato, error empty input, smoke skippato in
ambienti senza Pandoc): 92 test totali.
Smoke E2E via MCP: una sola chiamata `document_generate` con
`output_format=all` produce MD (14 KB), PDF (137 KB, 4 pagine A4) e
DOCX (12.7 KB) coerenti tra loro.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Aggiunge la possibilità di convertire un documento Markdown in PDF
direttamente lato server, senza richiedere al chiamante di avere
md-to-pdf, pandoc o altri tool sull'host. Il PDF è restituito come
stringa base64 nella risposta JSON-RPC, pronto a essere salvato,
allegato o spedito al cliente.
- pdf_renderer.py: nuovo modulo che parsea il frontmatter YAML del
Markdown (incluso il blocco pdf_options stile Puppeteer/md-to-pdf),
rende il body in HTML via markdown-it-py (supporta tabelle e
HTML inline) e produce il PDF tramite Chromium headless gestito
da Playwright. Le pdf_options camelCase (printBackground,
displayHeaderFooter, headerTemplate, ...) vengono tradotte negli
argomenti snake_case di page.pdf().
- mcp_tools.py: nuovo tool `document_to_pdf(markdown)` che ritorna
`{pdf_b64, size_bytes}`; `document_generate` esteso con il
parametro `output_format ∈ {md, pdf, both}` per emettere il PDF
contestualmente alla generazione del Markdown.
- pyproject.toml + uv.lock: aggiunte le dipendenze playwright>=1.48
e markdown-it-py[plugins]>=3.0.
- mcp-docugen.Dockerfile: nuova fase di runtime che installa le
librerie native richieste da Chromium (libnss3, libgbm1, ecc.) e
scarica il binario Chromium di Playwright in /opt/ms-playwright.
- 7 nuovi test unit (83 totali) che coprono lo split del frontmatter,
il rendering Markdown→HTML con tabelle, la traduzione delle
pdf_options camelCase→snake_case e l'errore su YAML invalido. Il
test E2E che richiede Chromium è marcato skip in unit; lo smoke
via MCP conferma generazione PDF da 134 KB / 4 pagine.
README aggiornato con le tre strade di conversione (server-side,
client-side, bundling) e la stima del nuovo costo immagine.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Problema: i template puntavano a un path host hardcoded
(stylesheet: /home/adriano/.../themes/tielogic.css), quindi il file .md
generato non era portabile — su un'altra macchina md-to-pdf non trovava
il CSS e produceva PDF senza stile.
Soluzione: il Renderer legge il CSS da Settings.inline_stylesheet_path
(default /app/themes/tielogic.css nel container) e lo inietta come
blocco <style>...</style> subito dopo il frontmatter YAML del Markdown
restituito dall'LLM. Il file .md risultante è autocontenuto e portabile.
- renderer.py: nuovo arg inline_stylesheet_path + funzione
_inject_inline_stylesheet (idempotente, gestisce Markdown senza
frontmatter, no-op se CSS vuoto)
- config.py: Settings.inline_stylesheet_path: Path | None
- main.py: passa il path al Renderer
- mcp-docugen.Dockerfile: COPY themes ./themes nello stage builder per
trasportare /app/themes/tielogic.css nell'immagine runtime
- templates_seed/{offerta,report-analisi}/template.md: rimossa la riga
`stylesheet:` dal frontmatter di output + regola tassativa che vieta
all'LLM di emettere blocchi <style> di sua iniziativa (evita
conflitti di cascade visti in test)
- 4 nuovi test unit (76 totali): iniezione dopo frontmatter, prepend
quando frontmatter assente, no-op CSS vuoto, integrazione full E2E
via Renderer.generate
scripts/bundle-css.py: utility per fixare file .md legacy che
referenziavano stylesheet: come path host (sostituisce la riga con
<style> inline pescando il CSS dal repo)
README aggiornato con rationale e workflow.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Il nome "devnotes" era fuorviante: il theme è unico e copre sia i report
tecnici stile DEVNOTES (template "report-analisi") sia le offerte
economiche stile docx Tielogic (template "offerta"). Le classi sono
partizionate per uso ma vivono nello stesso file.
- themes/tielogic.css: header esteso con descrizione delle famiglie
di classi (status-card+badge per report, table.financial per offerte,
cover+acceptance comuni)
- templates_seed/{offerta,report-analisi}/template.md: aggiornato il
riferimento `stylesheet:` nel frontmatter
- README: chiarito che themes/ contiene un theme unico
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- templates_seed/{offerta,report-analisi}/template.md: template Tielogic
ufficiali versionati come sorgente di verità nel repo
- template_seed.py: copia idempotente seed→volume al boot, mai
sovrascrive template esistenti (preserva edit fatti via MCP runtime)
- config.py: nuova Settings.templates_seed_dir
(default /app/services/mcp-docugen/templates_seed)
- main.py: chiamata seed_templates() in build_app dopo TemplateStore init
- 4 nuovi test unit (idempotenza, skip se seed_dir mancante,
no-op su entry non valide). 72 test verde totali
Workflow: edit del template nel repo → rebuild image → al primo boot
il volume vuoto riceve i template; se il template esiste già nel
volume (es. modificato dall'utente via tool MCP) viene preservato.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- themes/tielogic-devnotes.css: stile DEVNOTES + offerta Tielogic per md-to-pdf
(cover bianca con logo+box FORNITORE/CLIENTE, tabelle finanziarie, badge,
status-card, sezione ACCETTAZIONE con firme, A4 portrait)
- main.py: exempt_paths estesi a /docs /redoc /openapi.json (Swagger UI
accessibile senza Bearer per esplorazione interattiva)
- README: stato mcp-docugen aggiornato, layout docker/gateway, setup completo
con docker compose + smoke test
Template runtime (offerta, report-analisi) vivono nel volume Docker
docugen-data, non versionati nel repo.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- streamable_http_app() espone /mcp internamente; mount a root evita doppio prefisso.
- mcp.session_manager.run() integrato nel lifespan FastAPI: l'app mounted non
riceve automaticamente il proprio lifespan -> la task group streamable-http
non veniva inizializzata e le richieste MCP fallivano con RuntimeError.
Smoke test end-to-end via gateway Caddy (porta 8090):
- MCP initialize handshake OK
- tools/list espone 6 tool corretti
- template_create + template_list: round-trip con persistenza su volume
- document_generate propaga LLMAuthError come MCP isError:true
- Registrato in claude mcp list: ✓ Connected
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Renderer: orchestratore generate() — validazione strict variabili,
materializzazione image vars come asset effimeri su disco + URL rewrite,
asset paths template da ./assets/X -> {PUBLIC_BASE_URL}/assets/<t>/X,
integrazione LLM error -> record success=0
- FastAPI sub-app: GET /health (no auth), /assets/{t}/{f} (auth+traversal check),
/generated/{gen_id}/{f} (410 su scaduto o mancante)
- FastMCP server con 6 tool: template_create/update/delete/list/get,
document_generate. Tools esposti anche via mcp.tools dict per test.
- main.build_app() compone http_app + FastMCP mount su /mcp + auth middleware
+ lifespan cleanup task TTL (24h). run() entry point per script console.
68 test passed. Build Docker arca-mcp-docugen:dev verificata,
/health endpoint risponde correttamente nel container.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Docs/sistema-documentale/: master architettura multi-wiki
- Docs/docugen-mcp/: design + implementation plan MCP server
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adriano