Configurar o servidor MCP e as habilidades do agente da Mainframe Assessment Tool

Visualizar

Este recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Nesta página, descrevemos como configurar e interagir com o servidor MCP do Mainframe Assessment Tool e instalar a habilidade do agente mat-backend-query. Ao usar o servidor MCP e a habilidade mat-backend-query, você pode analisar domínios de negócios, pesquisar recursos e recuperar métricas de complexidade e dependência das suas avaliações de mainframe usando comandos de linguagem natural. Para interagir com o servidor MCP, conecte-se por agentes de IA ou clientes do Protocolo de Contexto de Modelo (MCP), como o Antigravity.

Com o servidor MCP da Mainframe Assessment Tool, é possível fazer o seguinte:

• Listar e visualizar as avaliações atuais.
• Conheça os domínios de negócios descobertos nas suas avaliações.
• Pesquisar e filtrar recursos com base em diferentes critérios.
• Recuperar especificações de recursos, incluindo dependências e métricas de complexidade.
• Consulte árvores de chamadas, uso de tabelas de banco de dados e DB2 e métricas de E/S de conjuntos de dados de visualizações materializadas do PostgreSQL usando a habilidade mat-backend-query.

Para mais informações sobre o MCP, consulte O que é o Protocolo de Contexto de Modelo (MCP)?.

Antes de começar

Antes de ativar e se conectar ao servidor MCP, conclua as seguintes tarefas:

• Crie uma avaliação. É possível ativar o servidor MCP e instalar a skill mat-backend-query a qualquer momento, mas para consultar dados de avaliação é necessário ter pelo menos uma avaliação concluída na Mainframe Assessment Tool. Para mais informações, consulte Criar uma avaliação.
• Conceda as permissões necessárias. As permissões necessárias dependem do seu ambiente de implantação da Mainframe Assessment Tool:
  • Em uma instância de VM do Compute Engine, você precisa de permissão para definir metadados personalizados na instância. Para mais detalhes sobre as funções necessárias, consulte Definir e remover metadados personalizados.
  • Em um cluster do GKE, você precisa de permissão para atualizar implantações no cluster e configurar a ferramenta de linha de comando kubectl para se conectar a ele. Para mais informações, consulte Configurar o acesso ao cluster para o kubectl.
• Configure a Google Cloud CLI. Instale e configure a versão mais recente da Google Cloud CLI. Para mais informações, consulte Instalar a Google Cloud CLI.

Ativar o servidor MCP

O servidor MCP fica desativado por padrão. Para ativar o servidor MCP, siga as instruções do seu ambiente de implantação.

Em uma instância do Compute Engine

Para ativar o servidor MCP na instância do Compute Engine da Mainframe Assessment Tool, adicione a chave de metadados MAT_ENABLE_MCP e defina o valor como true executando o seguinte comando gcloud:

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

Substitua:

• INSTANCE_NAME: o nome da instância de VM.
• ZONE: a zona em que a instância de VM está localizada.

Se você definir a chave de metadados em uma VM em execução, reinicie a VM para que as mudanças entrem em vigor.

Em um cluster do GKE

Para ativar o servidor MCP em uma implantação do GKE, defina a variável de ambiente MAT_ENABLE_MCP no contêiner mcp-server como true:

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

Substitua VERSION pela versão da Mainframe Assessment Tool implantada no cluster. Essa versão também é o namespace da implantação (por exemplo, mainframe-assessment-2-8-0).

A atualização da variável de ambiente reinicia o pod da Mainframe Assessment Tool com o servidor MCP ativado. Como a Mainframe Assessment Tool é executada como um único pod, ela fica brevemente indisponível enquanto o novo pod é iniciado. Para desativar o servidor MCP, defina a variável de ambiente MAT_ENABLE_MCP como false.

Conectar-se ao servidor MCP

É possível se conectar ao servidor MCP usando agentes de IA padrão que oferecem suporte a conexões MCP por HTTP de streaming.

Para abrir essas instruções de configuração diretamente na Mainframe Assessment Tool, siga estas etapas:

1. Na Mainframe Assessment Tool, acesse a página Avaliações.
2. Na barra de ferramentas, clique em Usar com o Antigravity e selecione Configurar MCP.

O servidor MCP está localizado na rota /mcp/ na mesma porta usada para acessar a interface do Mainframe Assessment Tool. Para mais informações, consulte Acessar a VM da Mainframe Assessment Tool do seu computador ou Acessar a Mainframe Assessment Tool implantada no GKE do seu computador.

Exemplos de configuração

As seções a seguir mostram exemplos de como configurar diferentes agentes de IA para se conectar ao servidor MCP.

Substitua LOCAL_PORT pela porta local usada para acessar a interface da Mainframe Assessment Tool.

Antigravity

Para usar o Antigravity, configure o servidor MCP no arquivo mcp_config.json da seguinte maneira:

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

Para mais informações, consulte Protocolo de Contexto de Modelo (MCP).

Instalar e usar a habilidade de agente do Mainframe Assessment Tool

O Mainframe Assessment Tool oferece a habilidade do agente mat-backend-query para o Antigravity, que permite analisar árvores de chamadas de programas, dependências entre módulos, padrões de acesso a tabelas de banco de dados e uso de E/S de conjuntos de dados na sua avaliação usando comandos de linguagem natural em vez de escrever consultas SQL. Para consultar dados com essa habilidade, primeiro é necessário criar uma avaliação no Mainframe Assessment Tool.

Baixar e extrair a habilidade

Para fazer o download e extrair a habilidade do agente mat-backend-query, siga estas etapas:

1. Na Mainframe Assessment Tool, acesse a página Avaliações.
2. Na barra de ferramentas, clique em Usar com o Antigravity e selecione Baixar habilidade. O navegador faz o download de um arquivo ZIP chamado skill.zip.

3. No computador, abra um terminal e acesse o diretório do projeto local do Antigravity. Se o diretório .agents/skills não existir, crie-o e extraia skill.zip:

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

   Substitua:

   • PROJECT_ROOT: o caminho para o diretório do projeto local no computador em que você executa o Antigravity.
   • PATH_TO_ZIP: o caminho para o diretório onde você fez o download do arquivo skill.zip.

4. Confirme se os arquivos extraídos em PROJECT_ROOT correspondem à seguinte estrutura de diretórios:

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

Verificar a habilidade no Antigravity

Para verificar se o Antigravity detecta o servidor MCP e a habilidade mat-backend-query, siga estas etapas:

1. Inicie o Antigravity no diretório PROJECT_ROOT para que ele descubra o diretório .agents/skills/.
2. No chat do Antigravity, execute o comando /mcp para verificar se o servidor MCP mainframe-assessment-tool está conectado e expõe a ferramenta db_query_tool.
3. Execute o comando /skills para confirmar se a habilidade mat-backend-query foi carregada.

4. Se você já tiver concluído uma avaliação na Mainframe Assessment Tool, teste a habilidade inserindo o seguinte comando:

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

   Substitua ASSESSMENT_ID pelo ID da avaliação.

Ferramentas do servidor MCP

O servidor MCP da Mainframe Assessment Tool oferece ferramentas que permitem que os agentes de IA recuperem dados das suas avaliações.

ListAssessments

Lista todas as avaliações na instância da Mainframe Assessment Tool. Cada avaliação inclui o nome, o ID, a descrição e os carimbos de data/hora.

ListDomains

Lista os domínios de um determinado ID de avaliação da Mainframe Assessment Tool. Cada domínio inclui o nome, a descrição e o ID.

Argumentos

A tabela a seguir descreve os argumentos dessa ferramenta:

Nome	Tipo	Obrigatório	Descrição
AssessmentId	string	Sim	O ID da avaliação da Mainframe Assessment Tool.

ListAssets

Lista os recursos de um determinado ID de avaliação da Mainframe Assessment Tool. Cada recurso inclui o ID, o nome, o caminho, o tipo e os IDs de domínio atribuídos.

Argumentos

A tabela a seguir descreve os argumentos dessa ferramenta:

Nome	Tipo	Obrigatório	Descrição
AssessmentId	string	Sim	O ID da avaliação da Mainframe Assessment Tool.

FetchDomain

Busca os detalhes do domínio de um determinado ID de domínio e ID de avaliação da Mainframe Assessment Tool. Os detalhes do domínio incluem ID, nome, descrição e resumo.

Argumentos

A tabela a seguir descreve os argumentos dessa ferramenta:

Nome	Tipo	Obrigatório	Descrição
AssessmentId	string	Sim	O ID da avaliação da Mainframe Assessment Tool.
DomainId	string	Sim	O ID do domínio da Mainframe Assessment Tool.

FetchAsset

Busca o resumo da especificação de um recurso para um determinado ID de avaliação da Mainframe Assessment Tool. A especificação do recurso inclui o ID, o nome, o uso, a descrição, o gráfico de ETL e os mapas do BMS.

Argumentos

A tabela a seguir descreve os argumentos dessa ferramenta:

Nome	Tipo	Obrigatório	Descrição
AssessmentId	string	Sim	O ID da avaliação da Mainframe Assessment Tool.
AssetId	string	Sim	O ID do recurso da Mainframe Assessment Tool.
DetailedSpec	booleano	Não (padrão: false)	Se definido como verdadeiro, a resposta também inclui especificações de método com os casos de teste.

FetchAssetsCyclomaticComplexity

Busca as pontuações de complexidade ciclomática de uma lista de recursos para um determinado ID de avaliação do Mainframe Assessment Tool.

Argumentos

A tabela a seguir descreve os argumentos dessa ferramenta:

Nome	Tipo	Obrigatório	Descrição
AssessmentId	string	Sim	O ID da avaliação da Mainframe Assessment Tool.
AssetIds	string[]	Sim	Lista de IDs de recursos da Mainframe Assessment Tool.

SearchContent

Pesquisas no código-fonte, em especificações geradas com IA e em regras de negócios em uma avaliação específica do mainframe. Ela oferece suporte aos modos de pesquisa por palavras-chave (bm25), semântica (embedding) e híbrida (hybrid), permitindo que os usuários localizem recursos e documentação relevantes.

A ferramenta pode filtrar resultados por tipo de documento (source, spec ou bre), limitar o número de correspondências retornadas e, opcionalmente, recuperar o conteúdo completo dos documentos correspondentes.

Argumentos

A tabela a seguir descreve os argumentos dessa ferramenta:

Nome	Tipo	Obrigatório	Descrição
AssessmentId	string	Sim	O ID da avaliação da Mainframe Assessment Tool.
Query	string	Sim	A consulta de pesquisa.
DocTypes	string[]	Não	Filtre os resultados por tipo de documento. Os valores compatíveis são: source, spec ou bre.
Limit	integer	Não	Limita o número de correspondências retornadas.
IncludeContent	booleano	Não	Se definido como verdadeiro, a resposta também inclui o conteúdo completo dos documentos correspondentes. O valor padrão é false.
SearchMode	string	Não	O modo de pesquisa a ser usado. Os valores compatíveis são: bm25 (com base em palavras-chave), embedding (semântico) ou hybrid. O valor padrão é hybrid.

ExploreData

Executa um agente de IA interativo (Explorador de dados) que atua como analista de dados para sua avaliação. O agente pode consultar o banco de dados estruturado de uma avaliação específica para responder a perguntas complexas.

Argumentos

A tabela a seguir descreve os argumentos dessa ferramenta:

Nome	Tipo	Obrigatório	Descrição
AssessmentId	string	Sim	O ID da avaliação da Mainframe Assessment Tool.
Query	string	Sim	A pergunta ou consulta para análise de dados.

ListBusinessRulesExtractionJobs

Lista os jobs de regras de negócios para um determinado ID de avaliação da Mainframe Assessment Tool. A lista retornada inclui o ID, o nome, o status, o comando de foco e outras informações de cada job.

Argumentos

A tabela a seguir descreve os argumentos dessa ferramenta:

Nome	Tipo	Obrigatório	Descrição
AssessmentId	string	Sim	O ID da avaliação da Mainframe Assessment Tool.

ListBusinessRules

Lista as regras de negócios extraídas por um código da tarefa de extração de regras de negócios e um ID de avaliação da Mainframe Assessment Tool específicos. Para lidar com um grande número de regras, essa ação é compatível com paginação.

Argumentos

A tabela a seguir descreve os argumentos dessa ferramenta:

Nome	Tipo	Obrigatório	Descrição
AssessmentId	string	Sim	O ID da avaliação da Mainframe Assessment Tool.
JobId	string	Sim	O ID do job de extração de regras de negócios.
PageSize	string	Não	O tamanho da página a ser buscada. O valor máximo aceito é 25.
PageToken	string	Não	O token da página a ser buscada. Esse valor foi retornado por uma chamada anterior para essa ação.
OrderList	objeto	Não	A ordem em que os resultados serão retornados. Consulte as descrições por campo.
OrderList.OrderBy	string	Não	O nome do campo em que os resultados serão ordenados. Exemplos: business_rule_id, business_rule_name, status.
OrderList.Order	string	Não	A direção da ordem. Os valores compatíveis são: ASCENDING, DESCENDING.
Filter	objeto	Não	Filtrar os resultados retornados. Consulte as descrições por campo.
Filter.Status	string	Não	O status das regras de negócios para filtrar. Os valores compatíveis são: PENDING, VALIDATED, OBSOLETE.
Filter.Tags	string[]	Não	Lista de tags associadas às regras de negócios.
Filter.AssetIDs	string[]	Não	Lista de IDs de recursos da ferramenta de avaliação de mainframe associados às regras de negócios.

FetchJobSpec

Busca a especificação do job de extração de regras de negócios (BRE) para um ID de avaliação da Mainframe Assessment Tool.

Argumentos

A tabela a seguir descreve os argumentos dessa ferramenta:

Nome	Tipo	Obrigatório	Descrição
AssessmentId	string	Sim	O ID da avaliação da Mainframe Assessment Tool.
JobId	string	Sim	O ID do job de extração de regras de negócios (BRE).

db_query_tool

Executa consultas diretas e somente leitura do PostgreSQL SELECT no esquema do Mainframe Assessment Tool mat_views e retorna até 10.000 linhas como uma matriz JSON.

Use a habilidade mat-backend-query com essa ferramenta para que o agente siga as regras necessárias:

• Cada consulta precisa filtrar por um ID de avaliação específico (WHERE assessment_id = 'ASSESSMENT_ID').
• Somente instruções SELECT em relação a visualizações no esquema mat_views são permitidas.
• As consultas precisam incluir uma cláusula LIMIT explícita.

Argumentos

A tabela a seguir descreve os argumentos dessa ferramenta:

Nome	Tipo	Obrigatório	Descrição
query	string	Sim	A consulta PostgreSQL SELECT somente leitura a ser executada no esquema mat_views (máximo de 10.000 linhas retornadas).

Visualizações materializadas disponíveis

A tabela a seguir descreve as visualizações materializadas do PostgreSQL no esquema mat_views que podem ser consultadas com db_query_tool:

Ver	Descrição	Colunas principais
mat_views.called_dependency	Programe árvores de chamadas e dependências entre módulos em aplicativos de mainframe, utilitários do sistema e programas externos não resolvidos.	assessment_id, calling_module, calling_module_type, called_module, called_module_type, call_count
mat_views.databases	Métricas de uso do banco de dados e operações de acesso à tabela realizadas por programas de mainframe, incluindo tabelas do DB2 e não analisadas.	assessment_id, database_name, table_name, program_name, access_type, sql_statements_count, is_db2
mat_views.datasets	Uso de E/S de arquivos do nome do conjunto de dados (DSN, na sigla em inglês) do mainframe e mapeamentos de job para etapa da JCL, incluindo conjuntos de dados compartilhados que conectam vários jobs.	assessment_id, dataset_name, job_name, step_name, dd_name, program_name, io_operation, is_shared_bridge

Exemplos de uso

Confira exemplos de comandos em linguagem natural que um agente de IA pode responder usando as ferramentas do servidor MCP e a habilidade mat-backend-query para recuperar e processar dados de avaliação:

• Cenário: encontrar programas complexos em uma avaliação.
  • Comando do usuário: "Liste os 10 programas COBOL mais complexos na avaliação chamada AssessmentName."
• Cenário: encontre e filtre recursos que pertencem a um domínio comercial.
  • Comando do usuário: "Liste todos os jobs de JCL relacionados ao domínio DomainName na avaliação chamada AssessmentName."
• Cenário: receber dependências de recursos de uma avaliação.
  • Comando do usuário: "Quais são as dependências do job JCL JCLJobName na avaliação chamada AssessmentName?"
• Cenário: encontrar as regras de negócios extraídas de um job específico.
  • Comando do usuário: "Liste todas as regras de negócios extraídas por BusinessRuleJobName na avaliação chamada AssessmentName."
• Cenário: analisar dados de avaliação usando linguagem natural.
  • Comando do usuário: "Explique como funciona o fluxo de tratamento de dados do sistema de faturamento na avaliação chamada AssessmentName."
• Cenário: consulte árvores de chamadas de programas usando a habilidade mat-backend-query.
  • Comando do usuário: "Usando a habilidade mat-backend-query, encontre os 10 módulos mais chamados e os tipos de chamador para a avaliação 'ASSESSMENT_ID'."
• Cenário: analisar o acesso à tabela do banco de dados e o uso do conjunto de dados usando a habilidade mat-backend-query.
  • Comando do usuário: "Usando a habilidade mat-backend-query, liste todas as tabelas DB2 acessadas com operações de gravação ou atualização na avaliação 'ASSESSMENT_ID'."