Pular para o conteúdo principal

MCP - Model Context Protocol

Recurso para implementar o Model Context Protocol (MCP) que permite expor ferramentas (tools) através de scripts carregados dinamicamente da pasta app/mcp/. Cada script pode registar uma ou mais ferramentas que podem ser executadas remotamente, seguindo o padrão do MCP para integração com assistentes de IA.

O MCP carrega automaticamente todos os scripts JavaScript da pasta app/mcp/ e disponibiliza as ferramentas registadas para execução. Suporta middlewares para interceptar chamadas antes da execução, permitindo validações, logs, autorização, etc.

A configuração do servidor MCP é feita no ficheiro _app/config.json na secção mcp.server.

// Exemplo de script em app/mcp/calculadora.js
// Registar uma ferramenta de soma
_mcp.registerTool(
    'somar',
    'Soma dois números inteiros',
    _val.map()
        .set('type', 'object')
        .set('properties', _val.map()
            .set('a', _val.map().set('type', 'number').set('description', 'Primeiro número'))
            .set('b', _val.map().set('type', 'number').set('description', 'Segundo número'))
        )
        .set('required', _val.list().add('a').add('b')),
    (input) => {
        const resultado = input.get('a') + input.get('b');
        return _val.map().set('success', true).set('resultado', resultado);
    }
);

// Registar uma ferramenta de multiplicação
_mcp.registerTool(
    'multiplicar',
    'Multiplica dois números inteiros',
    _val.map()
        .set('type', 'object')
        .set('properties', _val.map()
            .set('a', _val.map().set('type', 'number').set('description', 'Primeiro número'))
            .set('b', _val.map().set('type', 'number').set('description', 'Segundo número'))
        )
        .set('required', _val.list().add('a').add('b')),
    (input) => {
        const resultado = input.get('a') * input.get('b');
        return _val.map().set('success', true).set('resultado', resultado);
    }
);
// Exemplo de listagem e execução de ferramentas
// Listar todas as ferramentas disponíveis
const tools = _mcp.listAvailableTools();
for (const tool of tools) {
    _log.info('Ferramenta: ' + tool.get('name') + ' - ' + tool.get('description'));
}

// Executar uma ferramenta
const resultado = _mcp.executeTool('somar', _val.map().set('a', 5).set('b', 3));
if (resultado.get('success')) {
    _log.info('Resultado: ' + resultado.get('resultado'));
}

addMiddlewares​

_mcp.addMiddlewares(middlewares: org.netuno.tritao.resource.MCP$MCPMiddleware[]) : void​

Descrição​

Adiciona middlewares que serão executados antes de cada ferramenta. Se um middleware retornar um resultado não nulo, a execução da ferramenta é interrompida e esse resultado é retornado.

Como Usar​
// Exemplo de middleware para logging
_mcp.addMiddlewares((tool) => {
    _log.info('Executando ferramenta: ' + tool.name);
    return null; // Continua execução
});
Atributos​
NOMETIPODESCRIÇÃO
middlewaresorg.netuno.tritao.resource.MCP$MCPMiddleware[]Um ou mais middlewares a adicionar.
Retorno​

( void )

containsTool​

_mcp.containsTool(nome: string) : boolean​

Descrição​

Verifica se existe uma ferramenta registada com o nome especificado.

Como Usar​
if (_mcp.containsTool('somar')) {
    _log.info('Ferramenta de soma está disponível');
}
Atributos​
NOMETIPODESCRIÇÃO
nomestringNome da ferramenta a verificar.
Retorno​

( boolean )

Verdadeiro se a ferramenta existir, falso caso contrário.

executeTool​

_mcp.executeTool(nome: string, input: Values) : Values​

Descrição​

Executa uma ferramenta registada com os parâmetros fornecidos. Se a ferramenta não existir, retorna um objeto com success: false e uma mensagem de erro. Se algum middleware interromper a execução, retorna o resultado do middleware. Se ocorrer um erro durante a execução, retorna um objeto com success: false e a mensagem de erro.

Como Usar​
const resultado = _mcp.executeTool('somar', _val.map().set('a', 10).set('b', 20));
if (resultado.get('success')) {
    _log.info('Resultado: ' + resultado.get('resultado'));
} else {
    _log.error('Erro: ' + resultado.get('error'));
}
Atributos​
NOMETIPODESCRIÇÃO
nomestringNome da ferramenta a executar.
inputValuesObjeto com os parâmetros de entrada conforme o esquema definido no registo da ferramenta.
Retorno​

( Values )

Resultado da execução. Em caso de sucesso, contém success: true e os dados retornados pela ferramenta. Em caso de erro, contém success: false e error com a mensagem de erro.

getServerInfo​

_mcp.getServerInfo() : Values​

Descrição​

Obtém as informações do servidor MCP, incluindo nome e versão configurados.

Como Usar​
const info = _mcp.getServerInfo();
_log.info('Server: ' + info.get('name') + ' v' + info.get('version'));
Retorno​

( Values )

Objeto com os campos name (nome do servidor) e version (versão do servidor).

init​

_mcp.init() : void​

Retorno​

( void )

isEnabled​

_mcp.isEnabled() : boolean​

Descrição​

Verifica se o servidor MCP está ativo e disponível para processar requisições.

Como Usar​
if (_mcp.isEnabled()) {
    _log.info('MCP server is active');
}
Retorno​

( boolean )

Verdadeiro se o servidor MCP estiver ativo, falso caso contrário.

listAvailableTools​

_mcp.listAvailableTools() : Values​

Descrição​

Lista todas as ferramentas registadas no servidor MCP, incluindo nome, descrição e esquema de entrada.

Como Usar​
const tools = _mcp.listAvailableTools();
for (const tool of tools) {
    _log.info('Nome: ' + tool.get('name'));
    _log.info('Descrição: ' + tool.get('description'));
    _log.info('Esquema: ' + JSON.stringify(tool.get('inputSchema')));
}
Retorno​

( Values )

Lista de objetos, cada um contendo os campos: name (nome da ferramenta), description (descrição) e inputSchema (esquema JSON dos parâmetros).

registerTool​

_mcp.registerTool(nome: string, descricao: string, schema: Values, execute: java.util.function.Function<Values, Values>) : void​

Descrição​

Regista uma nova ferramenta no servidor MCP, tornando-a disponível para execução remota. O esquema deve seguir o formato JSON Schema para validação dos parâmetros de entrada.

Como Usar​
_mcp.registerTool(
    'saudacao',
    'Retorna uma saudação personalizada',
    _val.map()
        .set('type', 'object')
        .set('properties', _val.map()
            .set('nome', _val.map().set('type', 'string').set('description', 'Nome da pessoa'))
        )
        .set('required', _val.list().add('nome')),
    (input) => {
        return _val.map()
            .set('success', true)
            .set('mensagem', 'Olá, ' + input.get('nome') + '!');
    }
);
Atributos​
NOMETIPODESCRIÇÃO
nomestringNome único da ferramenta. Deve ser usado para executar a ferramenta posteriormente.
descricaostringDescrição textual da funcionalidade da ferramenta.
schemaValuesEsquema JSON que define os parâmetros de entrada da ferramenta.
executejava.util.function.FunctionFunção que implementa a lógica da ferramenta. Recebe os parâmetros de entrada e retorna o resultado.
Retorno​

( void )