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>
217 lines
12 KiB
Markdown
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.
|