Configura le skill dell'agente e del server MCP di Mainframe Assessment Tool

Questa pagina descrive come configurare e interagire con il server MCP di Mainframe Assessment Tool e installare lo skill dell'agente mat-backend-query. Utilizzando il server MCP e la skill mat-backend-query, puoi esplorare i domini aziendali, cercare asset e recuperare metriche di complessità e dipendenza dalle valutazioni del mainframe utilizzando prompt in linguaggio naturale. Per interagire con il server MCP, connettiti tramite agenti AI o client Model Context Protocol (MCP), come Antigravity.

Utilizzando il server MCP del Mainframe Assessment Tool, puoi:

  • Elencare e visualizzare le valutazioni esistenti.
  • Esplora i domini aziendali rilevati nelle tue valutazioni.
  • Cercare e filtrare le risorse in base a criteri diversi.
  • Recupera le specifiche degli asset, incluse le metriche di dipendenza e complessità.
  • Esegui query su alberi delle chiamate, utilizzo di DB2 e tabelle di database e metriche di I/O dei set di dati dalle viste materializzate di PostgreSQL utilizzando la skill mat-backend-query.

Per ulteriori informazioni sull'MCP, consulta Che cos'è il Model Context Protocol (MCP)?.

Prima di iniziare

Prima di attivare e connetterti al server MCP, completa le seguenti attività:

  • Crea un test. Puoi attivare il server MCP e installare la skill mat-backend-query in qualsiasi momento, ma per eseguire query sui dati di valutazione è necessaria almeno una valutazione completata in Mainframe Assessment Tool. Per maggiori informazioni, consulta Crea una valutazione.
  • Concedi le autorizzazioni necessarie. Le autorizzazioni necessarie dipendono dall'ambiente di deployment di Mainframe Assessment Tool:
    • Su un'istanza VM di Compute Engine, devi disporre dell'autorizzazione per impostare i metadati personalizzati sull'istanza. Per informazioni dettagliate sui ruoli richiesti, vedi Imposta e rimuovi i metadati personalizzati.
    • Su un cluster GKE, devi disporre dell'autorizzazione per aggiornare i deployment nel cluster e devi configurare lo strumento a riga di comando kubectl per connetterti al cluster. Per saperne di più, consulta Configura l'accesso ai cluster per kubectl.
  • Configura Google Cloud CLI. Installa e configura l'ultima versione di Google Cloud CLI. Per saperne di più, consulta Installa Google Cloud CLI.

Abilita il server MCP

Il server MCP è disattivato per impostazione predefinita. Per abilitare il server MCP, segui le istruzioni per l'ambiente di deployment.

Su un'istanza Compute Engine

Per attivare il server MCP sull'istanza Compute Engine di Mainframe Assessment Tool, aggiungi la chiave dei metadati MAT_ENABLE_MCP e imposta il relativo valore su true eseguendo il seguente comando gcloud:

    gcloud compute instances add-metadata INSTANCE_NAME \
    --metadata=MAT_ENABLE_MCP=true \
    --zone=ZONE

Sostituisci quanto segue:

  • INSTANCE_NAME: il nome dell'istanza VM.
  • ZONE: la zona in cui si trova l'istanza VM.

Se imposti la chiave dei metadati su una VM in esecuzione, devi riavviare la VM affinché le modifiche vengano applicate.

Su un cluster GKE

Per abilitare il server MCP in un deployment GKE, imposta la variabile di ambiente MAT_ENABLE_MCP sul container mcp-server su true:

kubectl set env deployment/mat-apps --containers=mcp-server \
MAT_ENABLE_MCP=true --namespace=VERSION

Sostituisci VERSION con la versione di Mainframe Assessment Tool di cui è stato eseguito il deployment nel cluster. Questa versione è anche lo spazio dei nomi del deployment (ad esempio, mainframe-assessment-2-8-0).

L'aggiornamento della variabile di ambiente riavvia il pod Mainframe Assessment Tool con il server MCP abilitato. Poiché Mainframe Assessment Tool viene eseguito come un singolo pod, non è disponibile per un breve periodo mentre viene avviato il nuovo pod. Per disattivare il server MCP, imposta la variabile di ambiente MAT_ENABLE_MCP su false.

Connettiti al server MCP

Puoi connetterti al server MCP utilizzando agenti AI standard che supportano le connessioni MCP tramite HTTP trasmissibile.

Per aprire queste istruzioni di configurazione direttamente da Mainframe Assessment Tool, segui questi passaggi:

  1. In Mainframe Assessment Tool, vai alla pagina Valutazioni.
  2. Nella barra degli strumenti, fai clic su Utilizza con Antigravity, quindi seleziona Configura MCP.

Il server MCP si trova nel percorso /mcp/ sulla stessa porta utilizzata per accedere alla UI di Mainframe Assessment Tool. Per ulteriori informazioni, consulta Accedi alla VM di Mainframe Assessment Tool dal tuo computer o Accedi a Mainframe Assessment Tool di cui è stato eseguito il deployment in GKE dal tuo computer.

Esempi di configurazione

Le seguenti sezioni forniscono esempi di come configurare diversi agenti AI per connettersi al server MCP.

Sostituisci LOCAL_PORT con la porta locale utilizzata per accedere alla UI di Mainframe Assessment Tool.

Antigravity

Per utilizzare Antigravity, configura il server MCP nel file mcp_config.json nel seguente modo:

{
  "mcpServers": {
    "mainframe-assessment-tool": {
      "serverUrl": "http://localhost:LOCAL_PORT/mcp/"
    }
  }
}

Per saperne di più, consulta Model Context Protocol (MCP).

Installare e utilizzare la skill dell'agente Mainframe Assessment Tool

Mainframe Assessment Tool fornisce la skill dell'agente mat-backend-query per Antigravity, che ti consente di analizzare gli alberi delle chiamate dei programmi, le dipendenze tra moduli, i pattern di accesso alle tabelle del database e l'utilizzo dell'I/O dei set di dati nella valutazione utilizzando prompt in linguaggio naturale anziché scrivere query SQL. Per eseguire query sui dati con questa skill, devi prima creare una valutazione in Mainframe Assessment Tool.

Scarica ed estrai la skill

Per scaricare ed estrarre l'abilità dell'agente mat-backend-query, segui questi passaggi:

  1. In Mainframe Assessment Tool, vai alla pagina Valutazioni.
  2. Nella barra degli strumenti, fai clic su Usa con Antigravity e poi seleziona Scarica skill. Il browser scarica un file ZIP denominato skill.zip.

  3. Sul computer, apri un terminale e vai alla directory locale del progetto Antigravity. Se la directory .agents/skills non esiste, creala, quindi estrai skill.zip:

    cd PROJECT_ROOT
mkdir -p .agents/skills
unzip PATH_TO_ZIP/skill.zip -d .agents/

    Sostituisci quanto segue:

    • PROJECT_ROOT: il percorso della directory del progetto locale sul computer in cui esegui Antigravity.
    • PATH_TO_ZIP: il percorso della directory in cui hai scaricato il file skill.zip.

  4. Verifica che i file estratti in PROJECT_ROOT corrispondano alla seguente struttura di directory:

    PROJECT_ROOT/
└── .agents/
    └── skills/
        ├── README.md
        └── mat-backend-query/
            ├── SKILL.md
            └── references/
                └── schemas.md

Verifica la skill in Antigravity

Per verificare che Antigravity rilevi il server MCP e la skill mat-backend-query, segui questi passaggi:

  1. Avvia Antigravity dalla directory PROJECT_ROOT in modo che rilevi la directory .agents/skills/.
  2. Nella chat di Antigravity, esegui il comando /mcp per verificare che il server MCP mainframe-assessment-tool sia connesso ed esponga lo strumento db_query_tool.
  3. Esegui il comando /skills per verificare che la skill mat-backend-query sia caricata.

  4. Se hai già completato una valutazione in Mainframe Assessment Tool, testa la skill inserendo il seguente prompt:

    Using the mat-backend-query skill, query 5 rows from mat_views.called_dependency for assessment 'ASSESSMENT_ID'.

    Sostituisci ASSESSMENT_ID con l'ID del tuo assessment.

Strumenti del server MCP

Il server MCP del Mainframe Assessment Tool fornisce strumenti che consentono agli agenti AI di recuperare i dati dalle valutazioni.

ListAssessments

Elenca tutte le valutazioni nell'istanza di Mainframe Assessment Tool. Ogni valutazione include il nome, l'ID, la descrizione e i timestamp.

ListDomains

Elenca i domini per un determinato ID valutazione di Mainframe Assessment Tool. Ogni dominio include il nome, la descrizione e l'ID.

Argomenti

La tabella seguente descrive gli argomenti per questo strumento:

Nome Tipo Obbligatorio Descrizione
AssessmentId string Sì L'ID della valutazione di Mainframe Assessment Tool.

ListAssets

Elenca gli asset per un determinato ID valutazione di Mainframe Assessment Tool. Ogni asset include l'ID, il nome, il percorso, il tipo e gli ID dominio assegnati.

Argomenti

La tabella seguente descrive gli argomenti per questo strumento:

Nome Tipo Obbligatorio Descrizione
AssessmentId string Sì L'ID della valutazione di Mainframe Assessment Tool.

FetchDomain

Recupera i dettagli del dominio per un determinato ID dominio e ID valutazione di Mainframe Assessment Tool. I dettagli del dominio includono ID, nome, descrizione e riepilogo.

Argomenti

La tabella seguente descrive gli argomenti per questo strumento:

Nome Tipo Obbligatorio Descrizione
AssessmentId string Sì L'ID della valutazione di Mainframe Assessment Tool.
DomainId string Sì L'ID del dominio Mainframe Assessment Tool.

FetchAsset

Recupera il riepilogo delle specifiche di un asset per un determinato ID valutazione di Mainframe Assessment Tool. La specifica dell'asset include ID, nome, utilizzo, descrizione, grafico ETL e mappe BMS.

Argomenti

La tabella seguente descrive gli argomenti per questo strumento:

Nome Tipo Obbligatorio Descrizione
AssessmentId string Sì L'ID della valutazione di Mainframe Assessment Tool.
AssetId string Sì L'ID della risorsa Mainframe Assessment Tool.
DetailedSpec boolean No (valore predefinito: false) Se è impostata su true, la risposta include anche le specifiche del metodo con i relativi scenari di test.

FetchAssetsCyclomaticComplexity

Recupera i punteggi di complessità ciclomati per un elenco di asset per un determinato ID valutazione di Mainframe Assessment Tool.

Argomenti

La tabella seguente descrive gli argomenti per questo strumento:

Nome Tipo Obbligatorio Descrizione
AssessmentId string Sì L'ID della valutazione di Mainframe Assessment Tool.
AssetIds string[] Sì Elenco degli ID asset di Mainframe Assessment Tool.

SearchContent

Esegue ricerche nel codice sorgente, nelle specifiche generate dall'AI e nelle regole aziendali all'interno di una valutazione specifica del mainframe. Supporta le modalità di ricerca basate su parole chiave (bm25), semantiche (embedding) e ibride (hybrid), consentendo agli utenti di trovare asset e documentazione pertinenti.

Lo strumento può filtrare i risultati per tipo di documento (source, spec o bre), limitare il numero di corrispondenze restituite e, facoltativamente, recuperare l'intero contenuto dei documenti corrispondenti.

Argomenti

La tabella seguente descrive gli argomenti per questo strumento:

Nome Tipo Obbligatorio Descrizione
AssessmentId string Sì L'ID della valutazione di Mainframe Assessment Tool.
Query string Sì La query di ricerca.
DocTypes string[] No Filtra i risultati per tipo di documento. I valori supportati sono: source, spec o bre.
Limit integer No Limita il numero di corrispondenze restituite.
IncludeContent boolean No Se è impostata su true, la risposta include anche l'intero contenuto dei documenti corrispondenti. Il valore predefinito è false.
SearchMode string No La modalità di ricerca da utilizzare. I valori supportati sono: bm25 (basato su parole chiave), embedding (semantico) o hybrid. Il valore predefinito è hybrid.

ExploreData

Esegue un agente AI interattivo (Data Explorer) che funge da analista di dati per la tua valutazione. L'agente può eseguire query sul database strutturato sottostante di una valutazione specifica per rispondere a domande complesse.

Argomenti

La tabella seguente descrive gli argomenti per questo strumento:

Nome Tipo Obbligatorio Descrizione
AssessmentId string Sì L'ID della valutazione di Mainframe Assessment Tool.
Query string Sì La domanda o la query per l'esplorazione dei dati.

ListBusinessRulesExtractionJobs

Elenca i job delle regole aziendali per un determinato ID valutazione di Mainframe Assessment Tool. L'elenco restituito include l'ID, il nome, lo stato, il prompt di selezione e altro ancora di ogni job.

Argomenti

La tabella seguente descrive gli argomenti per questo strumento:

Nome Tipo Obbligatorio Descrizione
AssessmentId string Sì L'ID della valutazione di Mainframe Assessment Tool.

ListBusinessRules

Elenca le regole aziendali estratte da un ID job di estrazione delle regole aziendali specifico e dall'ID valutazione dello strumento di valutazione del mainframe. Per gestire un numero elevato di regole, questa azione supporta l'impaginazione.

Argomenti

La tabella seguente descrive gli argomenti per questo strumento:

Nome Tipo Obbligatorio Descrizione
AssessmentId string Sì L'ID della valutazione di Mainframe Assessment Tool.
JobId string Sì L'ID del job di estrazione delle regole aziendali.
PageSize string No Le dimensioni della pagina da recuperare. Il valore massimo supportato è 25.
PageToken string No Il token della pagina da recuperare. Questo valore è stato restituito da una chiamata precedente a questa azione.
OrderList oggetto No L'ordine in cui restituire i risultati. Consulta le descrizioni per campo.
OrderList.OrderBy string No Il nome del campo in base al quale ordinare i risultati. Esempi: business_rule_id, business_rule_name, status.
OrderList.Order string No La direzione dell'ordine. I valori supportati sono: ASCENDING, DESCENDING.
Filter oggetto No Filtra i risultati restituiti. Consulta le descrizioni dei singoli campi.
Filter.Status string No Lo stato delle regole aziendali in base al quale filtrare. I valori supportati sono: PENDING, VALIDATED, OBSOLETE.
Filter.Tags string[] No Elenco di tag associati alle regole aziendali.
Filter.AssetIDs string[] No Elenco degli ID asset del Mainframe Assessment Tool associati alle regole aziendali.

FetchJobSpec

Recupera la specifica del job di estrazione delle regole aziendali (BRE) per un ID valutazione di Mainframe Assessment Tool.

Argomenti

La tabella seguente descrive gli argomenti per questo strumento:

Nome Tipo Obbligatorio Descrizione
AssessmentId string Sì L'ID della valutazione di Mainframe Assessment Tool.
JobId string Sì L'ID del job di estrazione delle regole aziendali (BRE).

db_query_tool

Esegue query PostgreSQL SELECT dirette e di sola lettura sullo schema di Mainframe Assessment Tool mat_views e restituisce fino a 10.000 righe come array JSON.

Utilizza la skill mat-backend-query con questo strumento in modo che l'agente segua le regole richieste:

  • Ogni query deve filtrare in base a un ID valutazione specifico (WHERE assessment_id = 'ASSESSMENT_ID').
  • Sono consentite solo istruzioni SELECT per le viste nello schema mat_views.
  • Le query devono includere una clausola LIMIT esplicita.

Argomenti

La tabella seguente descrive gli argomenti per questo strumento:

Nome Tipo Obbligatorio Descrizione
query string Sì La query PostgreSQL SELECT di sola lettura da eseguire sullo schema mat_views (massimo 10.000 righe restituite).

Viste materializzate disponibili

La tabella seguente descrive le viste materializzate di PostgreSQL nello schema mat_views su cui puoi eseguire query con db_query_tool:

Visualizza Descrizione Colonne chiave
mat_views.called_dependency Alberi delle chiamate di programma e dipendenze tra moduli in applicazioni mainframe, utilità di sistema e programmi esterni non risolti. assessment_id, calling_module, calling_module_type, called_module, called_module_type, call_count
mat_views.databases Metriche di utilizzo del database e operazioni di accesso alle tabelle eseguite dai programmi mainframe, incluse le tabelle DB2 e le tabelle non analizzate. assessment_id, database_name, table_name, program_name, access_type, sql_statements_count, is_db2
mat_views.datasets Utilizzo di I/O dei file del nome del set di dati (DSN) del mainframe e mappature dei job JCL ai passaggi, inclusi i set di dati condivisi che collegano più job. assessment_id, dataset_name, job_name, step_name, dd_name, program_name, io_operation, is_shared_bridge

Esempi di utilizzo

Di seguito sono riportati esempi di prompt in linguaggio naturale a cui un agente AI può rispondere utilizzando gli strumenti del server MCP e la skill mat-backend-query per recuperare ed elaborare i dati di valutazione:

  • Scenario: trovare programmi complessi in una valutazione.
    • Prompt dell'utente: "Elenca i 10 programmi COBOL più complessi nella valutazione denominata AssessmentName."
  • Scenario: trova e filtra gli asset che appartengono a un dominio aziendale.
    • Prompt dell'utente: "Elenca tutti i job JCL relativi al dominio DomainName nella valutazione denominata AssessmentName."
  • Scenario: recupera le dipendenze degli asset da una valutazione.
    • Prompt dell'utente: "Quali sono le dipendenze del job JCL JCLJobName nella valutazione denominata AssessmentName?"
  • Scenario: trova le regole aziendali estratte da un job specifico.
    • Prompt dell'utente: "Elenca tutte le regole aziendali estratte da BusinessRuleJobName nella valutazione denominata AssessmentName."
  • Scenario: esplora i dati di valutazione utilizzando il linguaggio naturale.
    • Prompt dell'utente: "Spiega come funziona il flusso di trattamento dati per il sistema di fatturazione nella valutazione denominata AssessmentName."
  • Scenario: esegui query sugli alberi delle chiamate del programma utilizzando la skill mat-backend-query.
    • Prompt dell'utente: "Utilizzando la skill mat-backend-query, trova i 10 moduli chiamati più di frequente e i relativi tipi di chiamante per la valutazione "ASSESSMENT_ID"."
  • Scenario: analizza l'accesso alle tabelle del database e l'utilizzo dei set di dati utilizzando la skill mat-backend-query.
    • Prompt utente: "Utilizzando la skill mat-backend-query, elenca tutte le tabelle DB2 a cui è stato eseguito l'accesso con operazioni di scrittura o aggiornamento nella valutazione 'ASSESSMENT_ID'."