# ArcaSuite

Monorepo per il **sistema documentale personale+aziendale** di Adriano e gli **MCP server** che lo supportano.

## Cos'è

Due pezzi, stesso repo:

1. **Sistema Documentale** — vault multi-wiki Markdown versionati su Gitea, pubblicati in sola lettura via Quartz, editabili da Obsidian + Claude Code. Vedi [`docs/sistema-documentale.md`](docs/sistema-documentale.md).
2. **MCP server** — microservizi MCP riusabili dai wiki (e da altri client Claude). Ogni MCP vive in `services/mcp-<nome>/` come membro del workspace `uv`.

## MCP previsti

| Servizio | Stato | Funzione |
|---|---|---|
| `mcp-docugen` | Implementato, 72 test verde, deploy Docker via gateway Caddy (porta 8090), 6 tool MCP esposti, template seed versionati con auto-seed al boot | Genera Markdown formale da template + LLM (OpenRouter). Vedi [`docs/mcp-docugen-design.md`](docs/mcp-docugen-design.md) + [`docs/mcp-docugen-implementation.md`](docs/mcp-docugen-implementation.md). |
| `mcp-convert` | Da progettare | Conversione Markdown → PDF / DOCX / HTML (pandoc/typst backend). |
| `mcp-inbox` | Da progettare | Ingest da Telegram (+ STT opzionale via Whisper) verso draft inbox consumati da Claude Code desktop. |

Ogni MCP ha il suo `pyproject.toml`, `src/mcp_<nome>/`, `tests/` e Dockerfile. Viene registrato in `pyproject.toml` root come workspace member.

## Layout

```
ArcaSuite/
├── docs/                         # design + implementation plan per componente
│   ├── sistema-documentale.md
│   ├── mcp-docugen-design.md
│   └── mcp-docugen-implementation.md
├── services/                     # workspace members uv (uno per MCP)
│   └── mcp-<nome>/               # src/ tests/ pyproject.toml Dockerfile
├── scripts/                      # script operativi (provisioning, backup, smoke)
├── secrets/                      # chiavi, token (gitignored)
├── docker/                       # base.Dockerfile condiviso multi-stage
├── gateway/                      # Caddy reverse proxy (Caddyfile)
├── themes/                       # CSS condivisi (theme Tielogic unico per md-to-pdf, copre report e offerte)
├── docker-compose.yml            # stack completo (gateway + servizi MCP)
├── pyproject.toml                # workspace uv + ruff + pytest root
├── .env.example                  # config root stack
├── .mcp.json.example             # template registrazione client MCP
└── .gitignore
```

## Convenzioni

- **Nomenclatura**: `mcp-<nome>` per tutti gli MCP (pattern Cerbero). Package Python: `mcp_<nome>` (snake_case).
- **Package manager**: `uv` workspace. Nessun `requirements.txt`. `uv.lock` committato.
- **Python**: 3.11+, async-first, Pydantic v2 per ogni I/O.
- **Testing**: `pytest` + `pytest-asyncio`, `asyncio_mode = "auto"`, test sotto `services/<svc>/tests/`.
- **Lint**: `ruff` (config root), line 100.
- **Config**: ogni servizio ha un proprio `.env.example`. Root `.env` solo per cose cross-cutting (gateway port, dominio pubblico).
- **Secrets**: mai committati. `.mcp.json` locale gitignored, solo `.mcp.json.example` tracciato.

## Riferimento spec Python

Servizi non-MCP (es. eventuali `inbox-service` REST) seguono [`/home/adriano/Documenti/Struttura_Progetti/2026-04-01-python-project-spec-design.md`](/home/adriano/Documenti/Struttura_Progetti/2026-04-01-python-project-spec-design.md). Gli MCP server seguono la struttura specifica descritta nei rispettivi design doc (FastMCP come root ASGI).

## Setup

```bash
cp .env.example .env             # imposta OPENROUTER_API_KEY, DOCUGEN_API_KEY, GATEWAY_PORT
cp .mcp.json.example .mcp.json   # compila con URL + API key per registrazione client
uv sync --all-groups
docker compose up -d --build     # avvia gateway + mcp-docugen
```

Smoke test:

```bash
curl -H "Authorization: Bearer $DOCUGEN_API_KEY" http://localhost:8090/mcp-docugen/health
```

Endpoint utili (richiede Bearer per quelli MCP, pubblici per la documentazione):

- `GET /mcp-docugen/health` — healthcheck (pubblico)
- `GET /mcp-docugen/docs` — Swagger UI REST (pubblico)
- `GET /mcp-docugen/redoc` — ReDoc REST (pubblico)
- `POST /mcp-docugen/mcp` — endpoint MCP JSON-RPC (Bearer + sessione MCP)

## Template `mcp-docugen`

I template ufficiali sono versionati in `services/mcp-docugen/templates_seed/<nome>/template.md` e copiati nel volume `docugen-data` al primo boot. La copia è **idempotente**: se un template esiste già nel volume (es. modificato a runtime via tool MCP `template_update`) non viene sovrascritto.

Template attualmente disponibili:

- `report-analisi` — report tecnico stile DEVNOTES Tielogic (analisi sperimentali, criticità, fattibilità, roadmap, accettazione)
- `offerta` — offerta economica stile docx Tielogic (cover FORNITORE/CLIENTE, modello commerciale setup+canone+sconto+proiezione, condizioni, accettazione)

Per propagare modifiche al template versionato su un'installazione esistente: usare il tool MCP `template_update`, oppure rimuovere il template dal volume e fare restart del container.

Conversione Markdown→PDF (in attesa di `mcp-convert`): `md-to-pdf <file>.md` con il CSS `themes/tielogic.css` referenziato dal frontmatter dei template.

## Remote

- Gitea: `ssh://git@git.tielogic.xyz:222/Adriano/ArcaSuite.git`