@my-ginkgo/noeva-compliance-mcp

Server MCP (Model Context Protocol) di NOEVA Adempia (spec NW-817). È un adattatore di protocollo, gemello di noeva-mcp-crm: traduce le tools/call MCP in chiamate HTTP verso la route category /api/workspaces/:id/compliance di noeva-server-api, con il livello di conferma delle scritture in mezzo. Nessuna logica di dominio, nessun accesso al database, nessun segreto NOEVA.

Due artefatti dallo stesso codice:

| Trasporto | Chi lo esegue | Chi lo usa | Autenticazione | | --------- | ---------------------------- | ------------------------------------------ | ------------------------------------------ | | HTTP | NOEVA (deploy centrale) | la piattaforma agenti | bearer token per richiesta | | stdio | il cliente (processo locale) | il suo client MCP (Claude Desktop, IDE, …) | NOEVA_API_KEY (una API key noeva_sk_…) |

Modello di sicurezza

• noeva-server-api è l'unico trust boundary: verifica token, workspace e appartenenza. Questo server inoltra Authorization: Bearer <token> e x-noeva-workspace: <id> e riporta la risposta. Un 401/403 dell'API diventa un errore di autorizzazione.
• Il token è opaco: mai decodificato qui.
• Le scritture richiedono conferma (elicitation o dry-run con confirm_token firmato), come nel MCP CRM. In R1 non esiste una coda di proposte: la conferma avviene in chat.

Tool

Un tool per dominio, l'operazione si sceglie con action. Ogni azione richiede workspace_id (UUID). La descrizione completa di ogni azione è nel tool stesso (src/tools/index.ts e i *Blurb.ts): è quella che legge l'agente.

| Tool | A cosa serve | | ---------------------------- | -------------------------------------------------------------------------------------------------- | | compliance_dashboard | Cruscotto del workspace: stato dei moduli, scadenze, documenti scaduti, evidenze da caricare | | compliance_setup | Profilo azienda, primo avvio, archivio, ri-onboarding, «Riconosci» (anteprima e applicazione) | | compliance_templates | Modelli dei moduli: domande di onboarding, anteprima e catalogo dei requisiti | | compliance_modules | Moduli del workspace in ogni stato e attivazione | | compliance_obligations | Registro degli obblighi con i requisiti delle norme, scadenze, adempimenti, passi, storico | | compliance_documents | Documenti, revisioni, copie firmate, firme, evidenze, confronto, materiali, esportazione, cassetta | | compliance_people | Persone, mansioni, firme per persona, esito delle visite (mai file sanitari) | | compliance_registers | Registri generati, storico importato, master da firmare | | compliance_tasks | Attività su CRM o Jira collegate agli obblighi | | compliance_risks | DVR: aree di rischio, misure, programma di miglioramento | | compliance_nonconformities | Non conformità e azioni correttive | | compliance_incidents | Incidenti di sicurezza e violazioni dei dati: scheda unica, 72 ore dalla scoperta, NC collegata | | compliance_soa | Statement of Applicability (ISO 27001) | | compliance_gdpr_processing | Registro dei trattamenti GDPR | | compliance_ai_systems | Registro dei sistemi di IA (AI Act) | | compliance_intake | Segnalazioni in ingresso (Formify, Jira, CRM) e proposte da decidere | | compliance_equipment | Presidi antincendio e di primo soccorso, presidi previsti ed esito della valutazione | | compliance_suppliers | Anagrafica fornitori: scheda, classe, cessazione, documenti collegati, valutazioni e scadenze | | compliance_admin | Responsabilità, notifiche dei membri, modelli di sistema e del workspace | | compliance_search | Ricerca globale per codice, titolo o riferimento su tutte le entità, con la posizione |

Ogni tool risponde a action: "help" con il suo manuale, intero o per azione (topic). Con topic: "index", da qualunque tool, restituisce l'indice azione → tool: per ogni azione, a cosa serve, in quale tool sta e chi può eseguirla. L'indice nasce da src/tools/actionGuide.ts, che un test tiene allineato alle azioni vere.

Le scritture chiedono conferma (elicitation, oppure dry-run e poi confirm_token). I dati sanitari non passano mai dall'MCP: si registra solo l'esito di una visita, il giudizio si carica dall'app.

Installazione pubblica (npm)

In produzione il MCP si distribuisce come pacchetto: al merge in main il workflow Release lo pubblica su GitHub Packages (@my-ginkgo/noeva-compliance-mcp) e su npm pubblico come @noeva/adempia-mcp. Gira dove gira il client MCP, non serve alcun PAT:

{
  "mcpServers": {
    "noeva-adempia": {
      "command": "npx",
      "args": ["-y", "@noeva/adempia-mcp"],
      "env": {
        "NOEVA_API_BASE_URL": "https://api.noeva.ai",
        "NOEVA_API_KEY": "noeva_sk_..."
      }
    }
  }
}

Uso locale (stdio)

pnpm install
cp .env.example .env   # NOEVA_API_BASE_URL=http://localhost:3002, NOEVA_API_KEY=noeva_sk_...
pnpm dev:stdio         # oppure: pnpm inspect

Config MCP (es. Claude Desktop), dopo pnpm build:

{
  "mcpServers": {
    "noeva-adempia": {
      "command": "node",
      "args": ["/percorso/noeva-mcp-compliance/dist/stdio.js"],
      "env": {
        "NOEVA_API_BASE_URL": "http://localhost:3002",
        "NOEVA_API_KEY": "noeva_sk_..."
      }
    }
  }
}

L'immagine ECR (gruppo4d/noeva-mcp-compliance, porta host 8093) resta predisposta ma non deployata, come per gli altri MCP: oggi si distribuiscono solo via stdio.

Sviluppo

pnpm typecheck && pnpm lint && pnpm test:coverage && pnpm format:check

I test chiamano i tool attraverso un client SDK collegato in memoria e un'API finta (test/integration/mcp.test.ts): nessuna rete, nessuna credenziale.