Files
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

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 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. 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."}}
  1. Notifica notifications/initialized (risposta 202 Accepted):
{"jsonrpc":"2.0","method":"notifications/initialized"}
  1. 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"]}}
]}}
  1. 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}}
  1. 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.