Passa al contenuto principale

🔌 Integrazione MCP: GitHub Copilot & Claude Desktop

Cos'è l'integrazione MCP?​

MCP (Model Context Protocol) è un protocollo aperto che consente agli assistenti AI come GitHub Copilot o Claude Desktop di connettersi a fonti di conoscenza esterne.

Con l'integrazione MCP, puoi:

  • ✅ Usare Alex direttamente in VS Code (tramite GitHub Copilot)
  • ✅ Usare Alex direttamente in Claude Desktop
  • ✅ Accedere alla conoscenza Business Central AL senza lasciare il tuo editor
  • ✅ Confrontare versioni di Business Central (BC 26 vs 27, ecc.)
Perché usare MCP?

Invece di passare tra VS Code e l'interfaccia web di Alex, poni le tue domande direttamente nel tuo editor di codice o in Claude Desktop. Alex risponde istantaneamente con informazioni precise su Business Central AL.

Assistenti compatibili​

GitHub Copilot (VS Code)​

GitHub Copilot è l'assistente AI integrato in Visual Studio Code. Con l'integrazione MCP:

  • Apri Copilot Chat in VS Code
  • Usa gli strumenti Alex: #mcp_alex_alex_al_query o #mcp_alex_alex_al_comparison
  • Fai le tue domande su Business Central AL
  • Alex risponde direttamente nella chat

Esempio:

Use #mcp_alex_alex_al_query to ask: How do I create a table extension in AL?

Claude Desktop​

Claude Desktop è l'applicazione desktop di Claude AI. Con l'integrazione MCP:

  • Apri Claude Desktop
  • Autorizza gli strumenti Alex (vedi sezione "Utilizzo" sotto)
  • Fai le tue domande normalmente nella conversazione
  • Claude usa automaticamente Alex per rispondere alle domande su Business Central

Esempio:

Explain the differences in table Customer between BC versions 26 and 27

Installazione​

Prerequisiti​

  • Node.js 18 o superiore installato sul tuo computer
  • Un account Alex attivo con crediti disponibili
  • GitHub Copilot (VS Code) o Claude Desktop installato

Installazione automatica (consigliata)​

Windows (PowerShell)​

  1. Clona il repository (https://github.com/pmoisontech/Alex-MCP-Proxy) o scarica il codice:

    git clone https://github.com/pmoisontech/Alex-MCP-Proxy.git
    cd Alex-MCP-Proxy/mcp-server-proxy

  2. Esegui l'installer:

    .\install-mcp.ps1

  3. Segui le istruzioni:

    • Inserisci l'URL del backend Alex (predefinito: https://alex.app.pmats.ai/api)
    • Inserisci il tuo nome utente Alex
    • Inserisci la tua password Alex
    • Scegli VS Code e/o Claude Desktop

  4. Riavvia il tuo assistente:

    • VS Code: Chiudi e riavvia VS Code completamente
    • Claude Desktop: Chiudi tutte le finestre e riavvia Claude

Linux / macOS / WSL​

  1. Clona il repository (https://github.com/pmoisontech/Alex-MCP-Proxy) o scarica il codice:

    git clone https://github.com/pmoisontech/Alex-MCP-Proxy.git
    cd Alex-MCP-Proxy/mcp-server-proxy

  2. Esegui l'installer:

    ./install-mcp.sh

  3. Segui le istruzioni:

    • Inserisci l'URL del backend Alex (predefinito: https://alex.app.pmats.ai/api)
    • Inserisci il tuo nome utente Alex
    • Inserisci la tua password Alex
    • Scegli VS Code e/o Claude Desktop

  4. Riavvia il tuo assistente:

    • VS Code: Chiudi e riavvia VS Code completamente
    • Claude Desktop: Chiudi tutte le finestre e riavvia Claude
Generazione chiave API

L'installer creerà automaticamente una chiave API per il tuo account Alex. Questa chiave è valida per 3 mesi per impostazione predefinita e consente al proxy MCP di autenticarsi con Alex.

Installazione manuale​

Se preferisci configurare manualmente, consulta il README del proxy MCP per istruzioni dettagliate.

Utilizzo​

Con GitHub Copilot (VS Code)​

  1. Apri VS Code e avvia un progetto AL
  2. Apri Copilot Chat (icona chat nella barra laterale)
  3. Usa gli strumenti Alex:

Per domande generali su AL:

Use #mcp_alex_alex_al_query to ask: How does the Customer table work in Business Central?

Per confrontare versioni:

Use #mcp_alex_alex_al_comparison to ask: What changed in table Sales Header between BC 26 and BC 27?
Scorciatoia

Digita #mcp per vedere tutti gli strumenti MCP disponibili. Seleziona #mcp_alex_alex_al_query o #mcp_alex_alex_al_comparison dall'elenco.

Con Claude Desktop​

  1. Apri Claude Desktop
  2. Apri Settings → All connectors
  3. Trova "alex" con 2 strumenti (alex_al_query, alex_al_comparison)
  4. Autorizza gli strumenti:
    • Clicca sul menu a discesa "Blocked"
    • Seleziona "Always allow"
    • Entrambi gli strumenti dovrebbero mostrare ✅ (autorizzato)
  5. Fai le tue domande normalmente nella conversazione

Claude rileverà automaticamente quando usare Alex per rispondere alle domande su Business Central.

Esempi di domande:

  • "How do I create a table extension in AL?"
  • "Show me an example of a codeunit that posts a sales order"
  • "What's new in the Sales Order page in BC 27?"
  • "Compare the Item table between versions 26 and 27"

Strumenti disponibili​

alex_al_query​

✅ Strumento predefinito per tutte le domande su Business Central AL (eccetto confronti di versione).

Utilizzi:

  • Informazioni su sintassi AL, oggetti, pattern
  • Risoluzione problemi codice AL
  • Best practice Business Central
  • Esempi di codice per funzionalità specifiche
  • Struttura di tabelle, pagine, codeunit

Esempi:

  • "How do I create a table extension in AL?"
  • "What's the syntax for posting a sales order in AL?"
  • "Show me examples of using RecordRef in Business Central"
  • "How to implement OnValidate trigger in AL?"

alex_al_comparison​

⚠️ Usa SOLO per confrontare versioni di Business Central (BC 26 vs 27, ecc.).

Utilizzi:

  • Confrontare codice AL tra due versioni BC
  • Identificare breaking change
  • Scoprire nuove funzionalità in una versione
  • Tracciare oggetti AL deprecati o obsoleti
  • Analizzare modifiche API tra versioni

Esempi:

  • "What changed in the Sales Header table between BC 26 and BC 27?"
  • "Compare the Item table between version 25 and 26"
  • "Show me breaking changes in Codeunit 80 from BC 24 to BC 25"
  • "What's new in the Sales Invoice page between version 26 and 27?"

Versioni supportate: BC 14 a 28 e successive. Formato:

  • Versione principale: "BC 26" (usa l'ultima versione minore disponibile)
  • Versione completa: "BC 26.5" o "BC 26.5.0.0"

Aggiornamento del proxy​

Se il proxy MCP è stato aggiornato (nuove funzionalità, correzioni bug):

  1. Aggiorna il codice:

    cd Alex-MCP-Proxy/mcp-server-proxy
    git pull origin main
    npm install

  2. Riavvia il tuo assistente:

    • VS Code: Chiudi e riavvia completamente
    • Claude Desktop: Chiudi tutte le finestre e riavvia
Modifiche importanti

Per aggiornamenti importanti con modifiche di configurazione, esegui nuovamente l'installer (./install-mcp.sh o .\install-mcp.ps1). Le tue impostazioni esistenti (chiave API, ecc.) saranno preservate.

Risoluzione problemi​

Alex non appare in GitHub Copilot​

Soluzioni:

  1. Verifica che il file mcp.json sia nella posizione corretta:
    • Windows: %APPDATA%\Code\User\mcp.json
    • Linux/macOS: ~/.config/Code/User/mcp.json
  2. Verifica che il percorso a mcp-proxy-client.js sia assoluto (non relativo)
  3. Riavvia VS Code completamente
  4. Verifica che la tua chiave API sia corretta nel file

Alex non appare in Claude Desktop​

Soluzioni:

  1. Verifica il file di configurazione:
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
    • Linux/macOS: ~/.config/Claude/claude_desktop_config.json
  2. Chiudi tutte le finestre di Claude Desktop e riavvia
  3. Verifica l'icona connectors in basso a destra in Claude
  4. Consulta i log: %APPDATA%\Claude\logs\ (Windows)

Strumenti bloccati in Claude Desktop​

Gli strumenti Alex appaiono ma sono contrassegnati "Blocked" (🚫):

Soluzione:

  1. Apri Settings → All connectors
  2. Trova "alex" nell'elenco
  3. Clicca sul menu a discesa "Blocked"
  4. Seleziona "Always allow"
  5. Gli strumenti dovrebbero ora mostrare ✅

Errore "401 Unauthorized"​

La tua chiave API non è valida o è scaduta.

Soluzione:

  1. Accedi all'interfaccia web Alex
  2. Vai a Impostazioni → Chiavi API
  3. Crea una nuova chiave API
  4. Sostituisci la chiave nel tuo file di configurazione (variabile ALEX_API_KEY)

Alex non risponde​

Soluzioni:

  1. Verifica la tua connessione Internet
  2. Verifica che l'URL del backend sia https://alex.app.pmats.ai/api
  3. Verifica di avere crediti disponibili sul tuo account Alex
  4. Attendi qualche secondo (la prima risposta può richiedere un momento)

Sicurezza e privacy​

  • La tua chiave API è personale e riservata - non condividerla mai
  • La connessione al backend Alex usa HTTPS (crittografato)
  • Le tue domande e il codice non sono archiviati permanentemente
  • Ogni utente ha un account isolato
Condivisione chiave API

MAI condividere la tua chiave API. Se pensi che sia stata compromessa, revocala immediatamente nelle impostazioni e creane una nuova.

Supporto​

Se riscontri un problema non coperto in questa documentazione:

  1. Verifica che Node.js sia installato (node --version dovrebbe mostrare ≥18)
  2. Verifica che i tuoi file di configurazione siano JSON valido
  3. Prova l'installer automatico se hai configurato manualmente
  4. Consulta GitHub issues
  5. Contatta il supporto con una descrizione precisa dell'errore

Ulteriori informazioni​