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>
12 KiB
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. API REST: 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 §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 intools/list; se chiamato comunque,tools/callrestituisce un errore JSON-RPC (proposta: codice-32001, messaggiopermission_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. 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;
idempotencyKeyha lo stesso significato dell'headerIdempotency-Keydella REST;- ogni scrittura finisce in
audit_logcon l'utente tecnico della chiave e nel log API/MCP.
5. Esempio di handshake
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."}}
- Notifica
notifications/initialized(risposta202 Accepted):
{"jsonrpc":"2.0","method":"notifications/initialized"}
tools/list:
{"jsonrpc":"2.0","id":2,"method":"tools/list"}
{"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"]}}
]}}
tools/call:
{"jsonrpc":"2.0","id":3,"method":"tools/call",
"params":{"name":"get_item_stock","arguments":{"itemCode":"ART-0001"}}}
{"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}}
ping:
{"jsonrpc":"2.0","id":4,"method":"ping"}
Prova rapida con curl (dopo aver letto Mcp-Session-Id dalla risposta di initialize):
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):
{
"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:
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) 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.