Files
Khaemhat/docs/MCP.md
T
Alby96andClaude Opus 5.5 88de272b3e docs: avoid ambiguous Unicode and record Gitea planning in STATUS
Gitea flags en dash, multiplication sign, minus sign and single angle
quotes as confusable characters, which put a warning on most pages;
use plain equivalents (docs/SPEC.md stays untouched). STATUS.md now
lists the issue numbers per milestone, the items waiting for the owner
and the open specification questions tracked by issue #114.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 22:44:14 +01:00

217 lines
12 KiB
Markdown

# Server MCP `/mcp`
> Stato: bozza · Revisione 2026-11-10 · Fonte: SPEC §7.3, §8.1, §15, §18, §21; mockup 088
Khaemhat espone un server **Model Context Protocol** su `/mcp` perché un agente AI (assistente in un client MCP,
automazione con un modello linguistico) possa leggere dati del gestionale e, se la chiave lo consente, eseguire
poche operazioni di scrittura controllate. Realizzato in **M12** (`v0.12.0`) con codice proprio
(`Khaemhat.Infrastructure/Mcp`: `McpServer`, `JsonRpc*`, `McpTool`, `McpToolRegistry`, `McpSchemaGenerator`;
endpoint `McpEndpoint` in `Khaemhat.Web`), senza SDK esterni.
Le parti marcate **(proposta)** non sono fissate da SPEC e vanno confermate in M12. Guida per l'utente:
[wiki MCP](wiki/MCP.md). API REST: [API.md](API.md).
---
## 1. Trasporto e protocollo
| Aspetto | Valore |
|---|---|
| Endpoint | `POST /mcp` (stessa origine dell'app, dietro il reverse proxy TLS) |
| Trasporto | **Streamable HTTP** (specifica MCP) |
| Messaggi | **JSON-RPC 2.0** (`jsonrpc`, `id`, `method`, `params` / `result` / `error`) |
| Risposte | `Content-Type: application/json` per ogni richiesta; nessun flusso SSE lato server **(proposta)**: `GET /mcp` risponde `405 Method Not Allowed` |
| Notifiche del client | (es. `notifications/initialized`) → `202 Accepted` senza corpo |
| Sessione | `Mcp-Session-Id` restituito nella risposta a `initialize` e richiesto nelle richieste successive **(proposta)**; `DELETE /mcp` chiude la sessione |
| Versione del protocollo | negoziata in `initialize`; la versione supportata è fissata in sviluppo e dichiarata in `McpServer` (il client la ripete nell'header `MCP-Protocol-Version`) |
| Licenza | modulo `API`; i tool di un modulo non licenziato **non compaiono** in `tools/list` (SPEC §8.1) |
| Log | sezione *API/MCP*, con `trace_id` per ogni chiamata |
## 2. Autenticazione
- Stessa chiave API della REST: `Authorization: Bearer kh_…` (SPEC §15). Hash SHA-256 nel database, prefisso
visibile, utente tecnico, permessi propri, azienda, scadenza, IP consentiti (SPEC §7.3).
- La chiave determina l'azienda; con una chiave di istanza serve l'header `X-Company: <codice>` (come in
[API.md](API.md) §2.3).
- I **tool di scrittura** sono abilitati **per chiave** (SPEC §15: "in scrittura opzionali per chiave"): una chiave
creata per un assistente può essere di sola lettura anche se l'utente tecnico ha permessi di scrittura.
- Chiave mancante o non valida → risposta HTTP `401` (problem+json, come la REST). Permesso mancante su un tool →
il tool non compare in `tools/list`; se chiamato comunque, `tools/call` restituisce un errore JSON-RPC
**(proposta: codice `-32001`, messaggio `permission_denied`)**.
## 3. Metodi JSON-RPC
| Metodo | Scopo | Risposta |
|---|---|---|
| `initialize` | negozia versione del protocollo e capacità | `protocolVersion`, `capabilities: { tools: {} }`, `serverInfo: { name: "khaemhat", version: "<semver>" }`, `instructions` (breve descrizione in italiano) |
| `tools/list` | elenca i tool disponibili **per questa chiave** (licenze + permessi) | `tools[]` con `name`, `description`, `inputSchema` (JSON Schema generato da `McpSchemaGenerator`) |
| `tools/call` | esegue un tool | `content[]` (testo leggibile) + `structuredContent` (JSON), `isError` |
| `ping` | verifica che il server risponda | `{}` |
Errori JSON-RPC standard: `-32700` parse error, `-32600` richiesta non valida, `-32601` metodo inesistente,
`-32602` parametri non validi. Gli errori **di dominio** di un tool (es. cliente bloccato per fido) si restituiscono
come risultato con `isError: true` e il messaggio localizzato, includendo il `traceId` (SPEC §9.5).
## 4. Tool
I nomi sono quelli di SPEC §15; parametri e permessi sono **proposte** coerenti con le API REST e con
[MODULES.md](MODULES.md). Tutti i tool di elenco accettano `limit` (default 20, massimo 100) e restituiscono al
massimo quella quantità di righe, per non saturare il contesto del modello.
### 4.1 Lettura
| Tool | Parametri | Restituisce | Permesso | Licenza |
|---|---|---|---|---|
| `search_parties` | `query` (testo: nome, codice, P.IVA, CF), `kind` (`customer`/`supplier`/`prospect`/`lead`, facoltativo), `limit` | elenco sintetico: id, codice, nome, P.IVA, città, stato | `parties.party.read` | CORE |
| `get_party` | `id` oppure `code` | scheda: dati principali, condizioni, fido e scaduto, contatti principali | `parties.party.read` | CORE |
| `search_items` | `query`, `categoryCode`, `limit` | id, codice, descrizione, UM, prezzo di listino base | `items.item.read` | CORE |
| `get_item_stock` | `itemCode`, `warehouseCode` (facoltativo) | per deposito: giacenza, impegnato, ordinato, disponibile, sottoscorta | `inventory.balance.read` | CORE |
| `get_document` | `type` (es. `invoice`, `sale_order`, `delivery_note`, `purchase_invoice`), `id` oppure `number` | testata, righe, totali, stato, stato SDI | permesso di lettura del tipo | CORE |
| `list_documents` | `type`, `partyCode`, `dateFrom`, `dateTo`, `status`, `limit` | elenco con numero, data, controparte, totale, stato | permesso di lettura del tipo | CORE |
| `get_open_items` | `partyCode` (facoltativo), `overdueOnly`, `dueBefore`, `limit` | partite: documento, scadenza, importo, residuo, giorni di ritardo, stato | `finance.open_item.read` | FIN |
| `sales_summary` | `dateFrom`, `dateTo`, `groupBy` (`customer`/`salesperson`/`category`/`item`/`month`), `limit` | fatturato per gruppo; margini solo con `items.cost.read` | `reports.report.read` | CORE (margini: REPORT) |
| `get_account_balance` | `accountCode`, `date` (facoltativo) | saldo dare/avere del conto alla data | `ledger.account.read` | ACCT |
| `trial_balance` | `fiscalYear`, `dateTo`, `level` (mastro/conto/sottoconto) | bilancio di verifica | `ledger.account.read` | ACCT |
| `vat_settlement_preview` | `period` (es. `2026-10` o `2026-Q3`) | anteprima della liquidazione: debito, credito, riporti, importo, codice tributo F24 | `vat.settlement.read` | ACCT |
| `crm_pipeline_summary` | `pipelineCode` (facoltativo), `ownerUsername` (facoltativo) | per fase: numero, valore, ponderato; chiusure attese | `crm.opportunity.read` | CRM |
| `get_log_errors` | `section` (facoltativo), `since`, `limit` | errori recenti del log: data, sezione, messaggio, `traceId` | **solo amministratori** (chiave di istanza, livello `Administrator` o superiore) | — |
### 4.2 Scrittura (opzionali per chiave)
| Tool | Parametri | Effetto | Permesso | Licenza |
|---|---|---|---|---|
| `create_sale_order` | `partyCode`, `date` (default oggi), `lines[]` (`itemCode`, `quantity`, `price` facoltativo, `discount` facoltativo), `notes`, `idempotencyKey` | crea un ordine cliente **in bozza** con prezzi risolti da `PriceResolver` se non indicati; restituisce numero provvisorio e link | `sales.order.write` | CORE |
| `create_party` | `kind`, `name`, `vatNumber`, `fiscalCode`, `address`, `email`, `pec`, `recipientCode`, `idempotencyKey` | crea cliente/prospect con codice automatico e validazioni (P.IVA, CF, codice destinatario) | `parties.party.write` | CORE |
| `create_crm_activity` | `kind` (chiamata/e-mail/riunione/attività/nota/visita), `subject`, `dueAt`, `partyCode` o `opportunityId`, `assigneeUsername`, `notes` | crea un'attività CRM | `crm.activity.write` | CRM |
Regole per i tool di scrittura **(proposta)**:
- creano solo **bozze** o record senza effetti fiscali: nessun tool emette fatture, contabilizza o invia allo SDI;
- `idempotencyKey` ha lo stesso significato dell'header `Idempotency-Key` della REST;
- ogni scrittura finisce in `audit_log` con l'utente tecnico della chiave e nel log *API/MCP*.
## 5. Esempio di handshake
1. `initialize`:
```
POST /mcp HTTP/1.1
Host: gestionale.example.com
Authorization: Bearer kh_test_0000000000000000000000
Content-Type: application/json
Accept: application/json, text/event-stream
{"jsonrpc":"2.0","id":1,"method":"initialize",
"params":{"protocolVersion":"<versione>","capabilities":{},
"clientInfo":{"name":"client-di-prova","version":"1.0"}}}
```
```
HTTP/1.1 200 OK
Content-Type: application/json
Mcp-Session-Id: 8c1d0b6e2f6a4e0f9b3a2c7d5e4f1a20
{"jsonrpc":"2.0","id":1,"result":{
"protocolVersion":"<versione>",
"capabilities":{"tools":{"listChanged":false}},
"serverInfo":{"name":"khaemhat","version":"1.0.0"},
"instructions":"Gestionale Khaemhat, azienda DEMO. Strumenti in sola lettura salvo diversa abilitazione della chiave."}}
```
2. Notifica `notifications/initialized` (risposta `202 Accepted`):
```json
{"jsonrpc":"2.0","method":"notifications/initialized"}
```
3. `tools/list`:
```json
{"jsonrpc":"2.0","id":2,"method":"tools/list"}
```
```json
{"jsonrpc":"2.0","id":2,"result":{"tools":[
{"name":"search_parties","description":"Cerca clienti, fornitori e prospect per nome, codice, partita IVA o codice fiscale.",
"inputSchema":{"type":"object","properties":{
"query":{"type":"string"},
"kind":{"type":"string","enum":["customer","supplier","prospect","lead"]},
"limit":{"type":"integer","minimum":1,"maximum":100,"default":20}},
"required":["query"]}}
]}}
```
4. `tools/call`:
```json
{"jsonrpc":"2.0","id":3,"method":"tools/call",
"params":{"name":"get_item_stock","arguments":{"itemCode":"ART-0001"}}}
```
```json
{"jsonrpc":"2.0","id":3,"result":{
"content":[{"type":"text","text":"ART-0001 · deposito SEDE: giacenza 120, impegnato 30, disponibile 90."}],
"structuredContent":{"itemCode":"ART-0001","warehouses":[
{"code":"SEDE","onHand":120,"committed":30,"onOrder":0,"available":90,"belowReorder":false}]},
"isError":false}}
```
5. `ping`:
```json
{"jsonrpc":"2.0","id":4,"method":"ping"}
```
Prova rapida con `curl` (dopo aver letto `Mcp-Session-Id` dalla risposta di `initialize`):
```bash
curl -s -X POST "https://gestionale.example.com/mcp" \
-H "Authorization: Bearer kh_test_0000000000000000000000" \
-H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
-H "Mcp-Session-Id: 8c1d0b6e2f6a4e0f9b3a2c7d5e4f1a20" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
```
## 6. Configurazione di un client MCP
La pagina *Amministrazione → Chiavi API, MCP e webhook* (mockup 088) mostra, per la chiave selezionata, l'elenco dei
tool esposti e un riquadro **Configurazione client MCP (esempio)** da copiare. Forma tipica (file di configurazione
JSON dei client che supportano server remoti HTTP):
```json
{
"mcpServers": {
"khaemhat": {
"type": "http",
"url": "https://gestionale.example.com/mcp",
"headers": { "Authorization": "Bearer kh_test_0000000000000000000000" }
}
}
}
```
Con una chiave di istanza aggiungere `"X-Company": "DEMO"` in `headers`. Con Claude Code da riga di comando:
```bash
claude mcp add --transport http khaemhat https://gestionale.example.com/mcp \
--header "Authorization: Bearer kh_test_0000000000000000000000"
```
Requisiti: URL pubblico HTTPS raggiungibile dal client (`KHAEMHAT_PUBLIC_URL`, reverse proxy TLS), modulo `API`
attivo, chiave con utente tecnico e flag "può usare le API".
## 7. Sicurezza
- Principio del minimo privilegio: una chiave dedicata per ogni agente, di sola lettura salvo necessità, con
scadenza e IP consentiti.
- I risultati dei tool contengono dati aziendali: il client MCP li passa al modello linguistico configurato
dall'utente. La wiki ([MCP](wiki/MCP.md)) lo dice esplicitamente.
- `get_log_errors` è riservato agli amministratori perché il log contiene dati tecnici di istanza.
- Rate limiting per chiave come per la REST; revoca immediata dalla pagina chiavi.
## 8. Test previsti (SPEC §18)
`Khaemhat.Web.Tests`: handshake MCP (`initialize` → `notifications/initialized` → `tools/list` → `tools/call` →
`ping`), filtro dei tool per licenza e permessi, tool di scrittura disabilitati su chiave di sola lettura, errori
JSON-RPC, `401` senza chiave.